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Preface 



This edition of the Amiga ROM Kernel Reference Manual: Libraries provides the latest information on how to 
program the Amiga line of personal computers from Commodore. It has been updated for Release 2 of the Amiga 
operating system and covers the newest Amiga computer systems including the A3000. 

This book is meant to help you learn how to program the Amiga. It assumes some previous experience with 
programming and familiarity with computers in general. Although it is not required, a knowledge of the C 
programming language will make it much easier to understand the material in this book. Most of the Amiga 
operating system is written in C (with the rest written in 68000 assembly language), hence C is the language 
used for the programming examples. 

This book is intended for the following audiences: 

C and assembly language programmers who want to create application software for the Amiga line of 
personal computers. 

Amiga software developers who want to upgrade their software for Release 2 of the operating system. 

Anyone who wants to know more about how the Amiga system software works. 

The Amiga system software is organized into related groups of functions called libraries. The same organization 
is used for this book. Here is a brief overview of the contents: 

Chapter 1 , Introduction to Amiga System Libraries. A look at the Amiga software and hardware 
architecture with an introduction to the basic elements of Amiga programming. 

Chapters 2-1 6, User Interface Libraries. An in-depth tutorial on how to create a graphic user interface 
for Amiga application software using Intuition and related modules including GadTools, Workbench, 
BOOPSI and ASL. 

Chapters 17-26, Exec Library. The details on how Exec, the system's master module, controls the 
system with working examples of interrupt processing code, subtask creation, lists and queues, 
semaphores, message passing and signalling. 

Chapters 27-30, Graphic Libraries. A complete explanation of the functions in the graphic and layers 
library that drive the Amiga's display hardware with examples of text rendering, line drawing, animation 
and more. 



Chapters 31 -37, Additional Libraries. Tutorials on how to use the Amiga commodities, DOS, IFFParse, 
keymap, translator and other important libraries in the operating system. 

Appendices. Special sections containing a debugging and troubleshooting guide plus a working example 
library for programmers who want to extend the capabilities of the operating system. 

We suggest that you use this book according to your level of familiarity with the Amiga system. Beginners should 
read the first four chapters and try the examples to get the basics. Then browse through the Exec chapters to get 
a deeper understanding of how the system works. 

Advanced Amiga programmers should read the chapters on new libraries like IFFParse and GadTools to find out 
what's new in Release 2. Also be sure to review the new Utility library to see how tag item lists have been used to 
implement many of the system improvements in Release 2. 

There are four other manuals in the Amiga Technical Reference Series. The Amiga ROM Kernel Reference 
Manual: Devices is a companion book to this volume detailing how to write code for the Amiga's lower level I/O 
hardware. The Amiga ROM Kernel Reference Manual: Includes and Autodocs is an alphabetically organized 
reference of ROM function summaries and system include files. Both these books are required reading for the 
serious programmer. 

Also available are the Amiga User Interface Style Guide, an application design specification and reference work 



describing how a standard Amiga application should look and feel; and the Amiga Hardware Reference Manual, 
an in-depth description of the custom chips and other hardware components underlying the Amiga's sophisticated 
design. 



VI 



Chapter 1 

INTRODUCTION TO AMIGA 

SYSTEM LIBRARIES 



The Amiga, like other microcomputers, contains a ROM full of routines that make programming the machine 
easier. The purpose of this book is to show you how to use these routines. Perhaps the best way to learn Amiga 
programming is by following examples and that is the method used in this book. Before starting though it will be 
helpful to go over some Amiga fundamentals. This section presents some of the basics that all Amiga 
programmers need to know. 

Programming in the Amiga Environment 

To program in the Amiga's dynamic environment you need to understand these special features of the Amiga's 
design: 

Multitasking (without memory protection) 

Shared libraries of functions 

Dynamic memory architecture (no memory map) 

Operating system versions 

Custom chips with DMA access (two kinds of memory) 



MULTITASKING 

The key feature of the Amiga's operating system design is multitasking. Multitasking means many programs, or 
tasks, reside in memory at the same time sharing system resources with one another. Programs take turns 
running so it appears that many programs are running simultaneously. 

Multitasking is based on the concept that a program spends most of its time waiting for things to happen. A 
program waits for events like key presses, mouse movement, or disk activity. While a program is waiting, the 
CPU is idle. The CPU could be used to run a different program during this idle period if there was a convenient 
method for rapidly switching from one program to another. This is what multitasking does. 
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What the System Does For You 

The Amiga uses pre-emptive multitasking which means that the operating system keeps track of all the tasks in 
memory and decides which one should run. The system checks hundreds of times per second to see which task 
should be run based on whether or not it is waiting, and other factors. Since the system handles all the work of 
task switching, multitasking is transparent to the application. From the application's point of view, it appears to 
have the machine all to itself. 

The Amiga OS also manages the sharing of resources between tasks. This is important because in order for a 
variety of tasks to run independently in the Amiga's multitasking environment, tasks must be prevented from 
interfering with one another. Imagine if five tasks were allowed to use the parallel port at the same time. The 
result would be I/O chaos. To prevent this, the operating system provides an arbitration method (usually a 
function call) for every system resource. For instance you must call a function, AllocMem(), to get exclusive 



access to a block of memory. 

What the System Doesn't Do For You 

The Amiga operating system handles most of the housekeeping needed for multitasking, but this does not mean 
that applications don't have to worry about multitasking at all. The current generation of Amiga systems do not 
have hardware memory protection, so there is nothing to stop a task from using memory it has not legally 
acquired. An errant task can easily corrupt some other task by accidentally overwriting its instructions or data. 
Amiga programmers need to be extra careful with memory; one bad memory pointer can cause the machine to 
crash (debugging utilities such as MungWall and Enforcer will prevent this). 

In fact, Amiga programmers need to be careful with every system resource, not just memory. All system 
resources from audio channels to the floppy disk drives are shared among tasks. Before using a resource, you 
must ask the system for access to the resource. This may fail if the resource is already being used by another 
task. 

Once you have control of a resource, no other task can use it, so give it up as soon as you are finished. When 
your program exits, you must give everything back whether it's memory, access to a file, or an I/O port. You are 
responsible for this, the system will not do it for you automatically. 



What Every Amiga Programmer Should Know. The Amiga is a multitasking computer. Keep 
in mind that other tasks are running at the same time as your application. Always ask the 
system for control of any resource you need; some other task may already be using it. Give it 
back as soon as you are done; another task may want to use it. This applies to just about 
every computing activity your application can perform, 
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LIBRARIES OF FUNCTIONS 

Most of the routines that make up the Amiga's operating system are organized into groups called libraries. h order 
to call a function on the Amiga you must first open the library that contains the function. For example, if you want 
to call the Read() function to read data from disk you must first open the DOS library. 

The system's master library, called Exec, is always open. Exec keeps track of all the other libraries and is in 
charge of opening and closing them. One Exec function, OpenLibraryQ, is used to open all the other libraries. 

Almost any program you write for the Amiga will have to call the OpenLibrary() function. Usage is as follows: 

struct Library *LibBase; /* Global: declare this above main ( ) */ 

main () 

{ 

LibBase = OpenLibraryf "library .name" , version) ; 

if ( !LibBase) 

{ 

/* Library did not open, so exit */ 

} 

else 

{ 

/* Library opened, so use its functions */ 

} 
} 

LibBase 

This is a pointer to the library structure in memory, often referred to as the library base. The library base must 
be global because the system uses it to handle the library's function calls. The name of this pointer is 
established by the system (you cannot use any name you want). Refer to the list below for the appropriate 



name. 

library.name 

This is a C string that describes the name of the library you wish to open. The list of Amiga library names is 
given below. 

version 

This should be set to the earliest acceptable library version. A value of matches any version. A value of 33 
means you require at least version 33, or a later version of the library. If the library version in the system is 
older than the one you specify, OpenLibrary() will fail (return 0). 

The table listed on the next page shows all the function libraries that are currently part of the Amiga system 
software. Column one shows the name string to use with OpenLibraryQ; column two shows the name of the 
global variable you should use to hold the pointer to the library; column three shows the oldest version of the 
library still in use. 
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Table 1-1 : Parameters to Use With OpenLibraryQ 



Library Name 

(library.name)* 


Library Base Name 

(LibBase) 


Oldest Version In Use 

(Version) 


asl. library 


Asl Base 


36 


commodities. library 


CxBase 


36 


diskfont. library 


DiskfontBase 


33 


dos. library 


DOSBase 


33 


exec.library 


SysBase 


33 


expansion. library 


ExpansionBase 


33 


gadtools. library 


GadToolsBase 


36 


graphics. library 


GfxBase 


33 


icon. library 


IconBase 


33 


iffparse. library 


IFFParseBase 


36 


intuition. library 


IntuitionBase 


33 


keymap.library 


KeymapBase 


33 


layers. library 


LayersBase 


33 


mathffp.library 


MathBase 


33 


mathtrans. library 


MathTransBase 


33 


mathieeedoubbas. library 


MathleeeDoubBasBase 


33 


mathieeedoubtrans. library 


MathleeeDoubTransBase 


33 


mathieeesingbas.library 


MathleeeSingBasBase 


33 


mathieeesingtrans.library 


MathleeeSingTransBase 


33 


rexxsyslib. library 


RexxSysBase 


36 


translator.library 


TranslatorBase 


33 


utility. library 


UtilityBase 


36 


workbench. library 


Workbench Base 


33 



* Other libraries may exist that are not supplied by Commodore since it is a feature of the operating system to 
allow such libraries. 



Opening a Library In C 

Call OpenLibrary() to open an Amiga function library. OpenLibrary() returns the address of the library structure 
(or library base) which you must assign to a specific global system variable as specified in the table above (case 
is important). 

If the library cannot open for some reason, the OpenLibraryQ function returns zero. Here's a brief example 
showing how it's used in C. 

/* easy.c: a complete example of how to open an Amiga function library in C. 

* In this case the function library is Intuition, Once the Intuition 

* function library is open, any Intuition function can be called. This 

* example uses the DisplayBeep ( ) function of Intuition to flash the screen. 

* With SAS/C (Lattice), compile with lc -L easy.c 
*/ 

/* Declare the return type of the functions we will use. */ 

struct Library *OpenLibrary ( ) ; /* These Exec library functions can be */ 

void CloseLibrary ( ) ; /* called anytime (Exec is always open) . */ 

void DisplayBeep ( ) ; /* Before using this Intuition function, */ 

/* the Intuition library must be opened */ 
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struct IntuitionBase *IntuitionBase; /* Get storage for the library base */ 

/* The base name MUST be IntuitionBase */ 
int main() 

{ 

IntuitionBase= (struct IntuitionBase *) OpenLibrary( "intuition. library" , 33L) ; 

if (IntuitionBase) /* Check to see if it actually opened. */ 

{ /* The Intuition library is now open so */ 

DisplayBeep (OL) ; /* any of its functions may be used. */ 

CloseLibrary (IntuitionBase) /* Always close a library if not in use. */ 

} 

else /* The library did not open so return an */ 

{ /* error code. The exit() function is */ 

exit (20); /* not part of the OS, it is part of the */ 

} /* compiler link library. */ 



Opening a Library in Assembler 

Here's the same example written in 68000 assembler. The principles are the same as with C: you must always 
open a library before using any of its functions. However, in assembler, library bases are treated a little differently 
than in C. In C, you assign the library base you get from OpenLibrary() to a global variable and forget about it 
(the system handles the rest). In assembler, the library base must always be in register A6 whenever calling any 
of the functions in the library. 

You get the library base for any library except Exec, by calling OpenLibrary(). For Exec, you get the library base 
from the longword in memory location 4 ($0000 0004). Exec is opened automatically by the system at boot time, 
and its library base is stored there. 

***************************************************************************** 



A complete ready-to-assemble example of how to open an Amiga function 
library in 68000 assembler. In this case the Intuition function library 
is opened and one of its functions, DisplayBeepO is called. 



* When calling an Amiga function, the library base pointer *must* be in 

* A6 (the library is free to depend on this). Registers DO, D1, AO 

* and A1 may be destroyed by the library, all others will be preserved. 

* 

AbsExecBase EQU 4 ;System pointer to Exec's library base 

XREF _LV00penl_ibrary ;Offset from Exec base for OpenLibrary() 
XREF _LVOCIoseLibrary ;Offset from Exec base for CloseLibrary() 
XREF _LVODisplayBeep ;Offset from Intuition base for DisplayBeep() 

move. I _AbsExecBase,a6 ;Move exec. library base to a6 

lea.l lntuiName(pc),al ;Pointer to "intuition. library" string 

moveq #33, dO ;Version of library needed 

jsr LVOOpenLibrary(a6) ;Call Exec's Openl_ibrary() and 

tst.l ao ;check to see if it succeeded 

bne.s open_ok 

moveq 820,d0 ;Set failure code 

rts ;Failed exit 



open_ok move. I d0,a6 
suba.l aO,aO 
jsr LVODisplayBeep(a6) 



Put IntuitionBase in a6. 

Load zero into aO 

Call Intuition's DisplayBeepQ 



move. I a6,a1 ;Put IntuitionBase into al 

move. I _AbsExecBase,a6 

jsr _LVOCIoseLibrary(a6) ;Call Exec's CloseLibrary() 

moveq #0,dO ;5et return code 

rts 

IntuiName: dc.b 'intuition. library', 
END 
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The Amiga library functions are set up to accept parameters in certain 68000 registers and always return results 
in data register DO. This allows programs and functions written in assembler to communicate quickly. It also 
eliminates the dependence on the stack frame conventions of any particular language. 

Amiga library functions use registers DO, D1 , AO and A1 . for work space and use register A6 to hold the library 
base. Do not expect these registers to be the same after calling a function. All routines return a full 32 bit 
longword unless noted otherwise. 

Another Kind of Function Library 

The Amiga has two kinds of libraries: run-time libraries and link libraries. All the libraries discussed so far are 
run-time libraries. Run-time libraries make up most of the Amiga's operating system and are the main topic of this 
book. 

There is another type of library known as a link library. Even though a link library is a collection of functions just 
like a run-time library, there are some major differences in the two types. 

Run-time libraries 

A run-time, or shared library is a group of functions managed by Exec that resides either in ROM or on disk 
(in the LIBS: directory). A run-time library must be opened before it can be used (as explained above). The 
functions in a run-time library are accessed dynamically at run-time and can be used by many programs at 
once even though only one copy of the library is in memory. A disk based run-time library is loaded into 
memory only if requested by a program and can be automatically flushed from memory when no longer 
needed. 

Link libraries 

A link library is a group of functions on disk that are managed by the compiler at link time. Link libraries do 
not have to be opened before they are used, instead you must link your code with the library when you 
compile a program. The functions in a link library are actually copied into every program that uses them. For 



instance the exitQ function used in the C program listed above is not part of any of the libraries that make 
up the Amiga OS. It comes from the link library supplied with the compiler (Ic.lib for SAS/Lattice C or c.lib for 
Manx Aztec C). The code that performs the exit() function is copied into the program when it is compiled. 

Libraries, Devices and Resources 

Most of the Amiga's OS routines are organized into groups of shared run-time libraries. The Amiga also has 
specialized function groups called devices and resources that programmers use to perform basic I/O operations 
or access low-level hardware. 

Devices and resources are similar in concept to a shared run-time library. They are managed by Exec and must 
be opened before they can be used. Their functions are separate from the programs that use them and are 
accessed dynamically at run time. Multiple programs can access the device or resource even though only one 
copy exists in memory (a few resources can only be used by one program at a time.) 
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Devices and resources are managed by Exec just as libraries are. For more information on devices and 
resources, see the chapter on "Exec Device I/O" later in this book or refer to the Amiga ROM Kernel Reference 
Manual: Devices for detailed descriptions of each device. 
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Figure 1-1 : Amiga System Software Hierarchy 
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What Every Amiga Programmer Should Know: The functions in the Amiga OS are accessed 
through shared run-time libraries. Libraries must be opened before their functions may be used. 
The system's master library, Exec, is always open. The Exec function OpenLibrary() is used to 
open all other libraries. 



DYNAMIC MEMORY ARCHITECTURE 

Unlike some microcomputer operating systems, the Amiga OS relies on absolute memory addresses as little as 
possible. Instead the Amiga OS uses a technique (sometimes referred to as soft machine architecture) which 
allows system routines and data structures to be positioned anywhere in memory. 

Amiga run-time libraries may be positioned anywhere in memory because they are always accessed through a 
jump table. Each library whether in ROM or loaded from disk has an associated Library structure and jump table 
in RAM. 



The system knows where the jump table starts in RAM because when a library is opened for the first time, Exec 
creates the library structure and keeps track of its location. The order of the entries in the library's jump-table is 
always preserved between versions of the OS but the functions they point to can be anywhere in memory. 
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Figure 1-1: Amiga Library Structure and Jump Table 

Hence, system routines in ROM may be moved from one version of the OS to another. Given the location of the 
jump table and the appropriate offset into the table, any function can always be found. 

Not only are system routines relocatable but system data structures are too. In the Amiga's multitasking 
environment, multiple applications run at the same time and each may have its own screen, memory, open files, 
and even its own subtasks. Since any number of application tasks are run and stopped at The user's option, 
system data structures have to be set up as needed. They cannot be set up ahead of time at a fixed memory 
location because there is no way to tell how many and what type will be needed. 



The Amiga system software manages this confusion by using linked lists of information about items such as 
libraries, tasks, screens, files and available memory. A linked list is a chain of data items with each data item 
containing a pointer to the next item in the chain. Given a pointer to the first item in a linked list, pointers to all the 
other items in the chain can be found. 
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Exec: The System Executive 

On the Amiga, The module that keeps track of linked lists is Exec, the system executive. Exec is the heart of the 
Amiga operating system since it also is in charge of multitasking, granting access to system resources (like 
memory) and managing the Amiga library system. 

As previously discussed, memory location 4 ($0000 0004), also known as SysBase, contains a pointer to the 
Exec library structure. This is the only absolutely defined location in the Amiga operating system. A program need 
only know where to find the Exec library to find, use and manipulate all other system code and data. 

The diagram above shows how the entire Amiga operating system is built as a tree starting at SysBase. Exec 
keeps linked lists of all the system libraries, devices, memory, tasks and other data structures. Each of these in 
turn can have its own variables and linked lists of data structures built onto it In this way, the flexibility of the OS 
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Figure 1-2: Exec and the Organization of the Amiga OS 



preserved so that upgrades can be made without jeopardizing compatibility. 



What Every Amiga Programmer Should Know: The Amiga has a dynamic memory map. 
There are no fixed locations for operating system variables and routines. Do not call ROM 
routines or access system data structures directly. Instead use the indirect access methods 
provided by the system. 
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OPERATING SYSTEM VERSIONS 

The Amiga operating system has undergone several major revisions summarized in the table below. The latest 
revision is Release 2 (corresponds to library versions 36 and above). 

System Library Kickstart release 

version 

number 

Any version 

30 Kickstart V 1 .0 (obsolete) 

31 Kickstart V 1 .1 (NTSC only - obsolete) 

32 Kickstart V 1 .1 (PAL only - obsolete) 

33 Kickstart V 1 .2 (the oldest revision still in use) 

34 Kickstart V 1 .3 (adds autoboot to V33) 

35 Special Kickstart version to support A2024 high-resolution monitor 

36 Kickstart V2.0 (old version of Release 2) 

37 Kickstart V2.04 (current version of Release 2) 

The examples listed throughout this book assume you are using Release 2. 

Many of the libraries and functions documented in this manual are available in all versions of the Amiga operating 
system. Others are completely new and cannot be used unless you have successfully opened the appropriate 
version of the library. 

To find out which functions are new with Release 2 refer to the ROM Kernel Reference Manual: Includes and 
Autodocs. The functions which are new are marked with (V36) or (V37) in the NAME line of the function Autodoc. 
These new functions require you to use a matching version number (36, 37, or higher) when opening the library. 

Exit gracefully and informatively if the required library version is not available. 

About Release 2 

Release 2 first appeared on the Amiga 3000. This initial version corresponds to Kickstart V2.00, system library 
version number V36. Release 2 was subsequently revised and this older version is now considered obsolete. 

Programs written for Release 2 should use only the later version corresponding to Kickstart V2.04, system library 
version number V37. If your system is using the earlier version of Release 2, you should upgrade your system. 
(Upgrade kits may be obtained from an authorized Commodore service center.) 



What Every Amiga Programmer Should Know: Some libraries or specific 
functions are not available in older versions of the Amiga operating system. Be 
sure to ask for the lowest library version that meets the requirements of your 
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THE CUSTOM CHIPS 

The most important feature of the Amiga's hardware design is the set of custom chips that perform specialized 
tasks independently of the CPU. Each of the custom chips (named Paula, Agnus, and Denise) is dedicated to a 
particular job: 

Paula (8364) Audio, floppy disk, serial, interrupts 

Agnus (8361/8370/8372) Copper (video coprocessor), blitter, DMA control 

Denise (8362) Color registers, color DACs (Digital to Analog Converters) and sprites 

The custom chips can perform work independently of the CPU because they have DMA, or Direct Memory 
Access, capability. DMA means the custom chips can access special areas of memory by themselves without 
any CPU involvement. (On computer systems without DMA, the CPU must do some or all of the memory 



handling for support chips.) The Amiga's custom chips make multitasking especially effective because they can 
handle things like rendering graphics and playing sound independently, giving the CPU more time to handle the 
overhead of task-switching and other important jobs. 

Custom Chip Revisions 

The custom chips have been revised as the Amiga platform has evolved and newer models of the Amiga 
developed. The latest revision of the Amiga custom chips is known as the Enhanced Chip Set, or ECS. Certain 
features of the Amiga operating system, such as higher resolution screens and special genlock modes, require 
the ECS version of the custom chips. In this book, features that require ECS are noted in the accompanying text. 
For more details about the special features of ECS, see Appendix C of the Amiga Hardware Reference Manual. 

Two Kinds of Memory 

To keep the Amiga running efficiently, the Amiga has two memory buses and two kinds of memory. Chip 
memory is memory that both the CPU and custom chips can access. Fast memory is memory that only the 
CPU (and certain expansion cards) can access. Since Chip memory is shared, CPU access may be slowed 
down if the custom chips are doing heavy-duty processing. CPU access to Fast memory is never slowed 
down by contention with the custom chips. 

The distinction between Chip memory and Fast memory is very important for Amiga programmers to keep 
in mind because any data accessed directly by the custom chips such as video display data, audio data or 
sprite data must be in Chip memory. 

What Every Amiga Programmer Should Know: The Amiga has two kinds of memory: Chip 
memory and Fast memory. Use the right kind. 
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About the Examples 

For the most part, the examples in this book are written in C (there are a few 68000 assembly language 
examples too). 

C examples have been compiled under SAS C, version 5.10a. The compiler options used with each 
example are noted in the comments preceding the code. 

In general, the examples are also compatible with Manx Aztec C 68K, version 6.0d, and other C compilers, 
however some changes will usually be necessary. Specifically, all the C examples assume that the 
automatic Ctrl-C feature of the compiler has been disabled. For SAS C (and Lattice C revisions 4.0 and 
greater) this is handled with: 

/* Add this before main ( ) to override the default Ctrl-C handling 
* provided in SAS (Lattice) C. Ctrl-C event will be ignored */ 
int CXBRK ( void ) { return (0); } 

int chkabort ( void ) ( return (0) ; } 

For Manx Aztec C, replace the above with: 

/* Add this near the top */ 
#include <f unctions . h> 

/* Add this before main() */ 

extern int Enable Abort; /* reference abort enable */ 

/* Add this after main ( ) , as the first active line in the program */ 
Enable Abort=0; /* turn off CTRL-C */ 



Other changes may be required depending on the example and the C compiler you are using. Most of the C 
examples in this book use the following special option flags of the SAS/C compiler (set the equivalent 
option of whatever compiler you are using): 

bl = Small data model. 

-cf =Check for function prototypes. 

i = I qnorei include statements that are identical to one already given. 

s=Storeall literal strings that are identical in the same place. 

t = Enable warnings for structures that are used before they are defined. 

-v =Do not include stack checking code with each function. 

-y =Load register A9 with the data section base address on function entry. 

The -v and -y flags are are generally only needed for parts of the 

program that are called directly by the system such as interrupt 

servers, subtasks, handlers and callback hook functions. 

Except where noted, each example was linked with the standard SAS/C startup code c.o, the SAS/C linker library 
Ic.lib and the Commodore linker library amiga.lib. The SAS/C compiler defaults to 32-bit ints. If your development 
environment uses 16-bit ints you may need to explicitly cast certain arguments as longs (for example 1L « sigbit 
instead Of 1 « sigbit). 

The 68000 assembly language examples have been assembled under the Innovatronics CAPE assembler V2.x, 
the HiSoft Devpac assembler V 1.2, and the Lake Forest Logic ADAPT assembler 1.0. No substantial changes 
should be required to switch between assemblers. 
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General Amiga Development Guidelines 

In the earlier sections of this chapter, the basic environment of the Amiga operating system was discussed. This 
sections presents specific guidelines that all Amiga programmers must follow. Some of these guidelines are for 
advanced programmers or apply only to code written in assembly language. 

Check for memory loss. Arrange your Workbench screen so that you have a Shell available and can 
start your program without rearranging any windows. In the Shell window type Avail flush several 
times (the flush option requires the Release 2 version of the Avail command). Note the total amount of 
free memory. Run your program (do not rearrange any windows other than those created by the 
program) and then exit. At the Shell, type Avail flush several times again. Compare the total amount of 
free memory with the earlier figure. They should be the same. Any difference indicates that your 
application is not freeing some memory it used or is not closing a disk-loaded library, device or font it 
opened. Note that under Release 2, a small amount of memory loss is normal if your application is the 
first to use the audio or narrator device. 

Use all of the program debugging and stress tools that are available when writing and testing your code. 
New debugging tools such as Enforcer, MungWall, and Scratch can help find uninitialized pointers, 
attempted use of freed memory and misuse of scratch registers or condition codes (even in programs 
that appear to work perfectly). 

Always make sure you actually get any system resource that you ask for. This applies to memory, 
windows, screens, file handles, libraries, devices, ports, etc. Where an error value or return is possible, 
ensure that there is a reasonable failure path. Many poorly written programs will appear to be reliable, 
until some error condition (such as memory full or a disk problem) causes the program to continue with 
an invalid or null pointer, or branch to untested error handling code. 

Always clean up after yourself. This applies for both normal program exit and program termination due 
to error conditions. Anything that was opened must be closed, anything allocated must be deallocated. It 
is generally correct to do closes and deallocations in reverse order of the opens and allocations. Be sure 
to check your development language manual and startup code; some items may be closed or 
deallocated automatically for you, especially in abort conditions. If you write in the C language, make 
sure your code handles Ctrl-C properly. 



Remember that memory, peripheral configurations, and ROMs differ between models and between 
individual systems. Do not make assumptions about memory address ranges, storage device names, or 
the locations of system structures or code. Never call ROM routines directly. Beware of any example 
code you find that calls routines at addresses in the $F0 0000 - $FF FFFF range. These are ROM 
routines and they will move with every OS release. The only supported interface to system ROM code 
is through the library, device, and resource calls. 

Never assume library bases or structures will exist at any particular memory location. The only absolute 
address in the system is $0000 0004, which contains a pointer to the Exec library base. Do not modify 
or depend on the format of private system structures. This includes the poking of copper lists, memory 
lists, and library bases. 

Never assume that programs can access hardware resources directly. Most hardware is controlled by 
system software that will not respond well to interference from other programs. Shared hardware 
requires programs to use the proper sharing protocols. Use the defined interface; it is the best way is 
ensure that your software will continue to operate on future models of the Amiga. 
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Never access shared data structures directly without the proper mutual exclusion (locking). Remember 
that other tasks may be accessing the same structures. 

The system does not monitor the size of a program's stack. (Your compiler may have an option to do 
this for you.) Take care that your program does not cause stack overflow and provide extra stack space 
for the possibility that some functions may use up additional stack space in future versions of the OS. 

Never use a polling loop to test signal bits. If your program waits for external events like menu selection 
or keystrokes, do not bog down the multitasking system by busy-waiting in a loop. Instead, let your task 
go to sleep by Wait()ing on its signal bits. For example: 

signals = (ULONG)Wait( (l<<windowPtr->UserPort->mp_SigBit) 

(l<<consoleMsgPortPtr->mp_SigBit) ) ; 

This turns the signal bit number for each port into a mask, then combines them as the argument for the 
Exec library Wait() function. When your task wakes up, handle all of the messages at each port where 
the mp_SigBit is set. There may be more than one message per port, or no messages at the port. Make 
sure that you ReplyMsgQ to all messages that are not replies themselves. If you have no signal bits to 
Wait() on, use Delay() or WaitTOF() to provide a measured delay. 

Tasks (and processes) execute in 680x0 user mode. Supervisor mode is reserved for interrupts, traps, 
and task dispatching. Take extreme care if your code executes in supervisor mode. Exceptions while in 
supervisor mode are deadly. 

Most system functions require a particular execution environment. All DOS functions and any functions 
that might call DOS (such as the opening of a disk-resident library, font, or device) can only be executed 
from a process. A task is not sufficient. Most other ROM kernel functions may be executed from tasks. 
Only a few may be executed from interrupts. 

Never disable interrupts or multitasking for long periods. If you use Forbid() or Disable(), you should be 
aware that execution of any system function that performs the Wait() function will temporarily suspend 
the Forbid() or Disable() state, and allow multitasking and interrupts to occur. Such functions include 
almost all forms of DOS and device I/O, including common stdio functions like printf(). 

Never tie up system resources unless it is absolutely necessary. For example, if your program does not 
require constant use of the printer, open the printer device only when you need it. This will allow other 
tasks to use the printer while your program is running. You must provide a reasonable error response if 
a resource is not available when you need it. 

All data for the custom chips must reside in Chip memory (type MEMF_CHIP). This includes bitplanes, 
sound samples, trackdisk buffers, and images for sprites, bobs, pointers, and gadgets. The AllocMem() 
call takes a flag for specifying the type of memory. A program that specifies the wrong type of memory 
may appear to run correctly because many Amigas have only Chip memory. (On all models of the 



Amiga, the first 51 2K of memory is Chip memory. In later models, Chip memory may occupy up to the 
first one or two megabytes). 

However, once expansion memory has been added to an Amiga (type MEMF_FAST), any memory 
allocations will be made in the expansion memory area by default. Hence, a program can run correctly 
on an unexpanded Amiga which has only Chip memory while crashing on an Amiga which has 
expanded memory. A developer with only Chip memory may fail to notice that memory was incorrectly 
specified. 
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Most compilers have options to mark specific data structures or object modules so that they will load into 
Chip RAM. Some older compilers provide the Atom utility for marking object modules. If this method is 
unacceptable, use the AllocMem() call to dynamically allocate Chip memory, and copy your data there. 

When making allocations that do not require Chip memory, do not explicitly ask for Fast memory. 
Instead ask for memory type MEMF_PUBLIC or OL as appropriate. If Fast memory is available, you will 
get it. 

Never use software delay loops! Under the multitasking operating system, the time spent in a loop can 
be better used by other tasks. Even ignoring the effect it has on multitasking, timing loops are inaccurate 
and will wait different amounts of time depending on the specific model of Amiga computer. The timer 
device provides precision timing for use under the multitasking system and it works the same on all 
models of the Amiga. The AmigaDOS Delay() function or the graphics library WaitTOFQ function 
provide a simple interface for longer delays. The 8520 I/O chips provide timers for developers who are 
bypassing the operating system (see the Amiga Hardware Reference Manual for more information). 

Always obey structure conventions! 

• All non-byte fields must be word-aligned. Longwords should be longword-aligned for performance. 

• All address pointers should be 32 bits (not 24 bits). Never use the upper byte for data. 

• Fields that are not defined to contain particular initial values must be initialized to zero. This includes 
pointer fields. 

• All reserved or unused fields must be initialized to zero for future compatibility. 

• Data structures to be accessed by the custom chips, public data structures (such as a task control 

block), and structures which must be longword aligned must nor be allocated on a program's 
stack. 

• Dynamic allocation of structures with AllocMem() provides longword aligned memory of a specified 

type with optional initialization to zero, which is useful in the allocation of structures. 

FOR 68010/68020/68030168040 COMPATIBILITY 

Special care must be taken to be compatible with the entire family of 68000 processors: 

Do not use the upper 8 bits of a pointer for storing unrelated information. The 68020, 68030, and 68040 
use all 32 bits for addressing. 

Do not use signed variables or signed math for addresses. 

Do not use software delay loops, and do not make assumptions about the order in which asynchronous 
tasks will finish. 
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The stack frame used for exceptions is different on each member of the 68000 family. The type 
identification in the frame must be checked! In addition, the interrupt autovectors may reside in a 
different location on processors with a VBR register. 

Do not use the MOVE SR, <dest>instruction! This 68000 instruction acts differently on other members 
of the 68000 family. If you want to get a copy of the processor condition codes, use the Exec library 
GetCC() function. 

Do not use the CLR instruction on a hardware register which is triggered by Write access. The 68020 
czR instruction does a single Write access. The 68000 CLR instruction does a Read access first, then a 
Write access. This can cause a hardware register to be triggered twice. Use MOVE.x #0, <address> 
instead. 

Self modifying code is strongly discouraged. All 68000 family processors have a pre-fetch feature. This 
means the CPU loads instructions ahead of the current program counter. Hence, if your code modifies 
or decrypts itself just ahead of the program counter, the pre-fetched instructions may not match the 
modified instructions. The more advanced processors prefetch more words. If self modifying code must 
be used, flushing the cache is the safest way to prevent troubles. 

The 68020, 68030 and 68040 processors all have instruction caches. These caches store recently used 
instructions, but do not monitor writes. After modifying or directly loading instructions, the cache must be 
flushed. See the Exec library CacheClearU() Autodoc for more details. If your code takes over the 
machine, flushing the cache will be trickier. You can account for the current processors, and hope the 
same techniques will work in the future: 

CACRF_Clearl EQU $0008 ;Bit for clear instruction cache 

Supervisor mode only. Use this only if you have taken over the 
machine. Read and store the ExecBase processor AttnPlags flags at 
boot time, call this code only if the "68020 or better" bit was set. 

ClearlCache: dew $4E7A, $0002 ;MOVEC CACR.DO 

tst.w dO ;movec does not affect CC's 

bmi.s cic_040 ;A 68040 with enabled cache! 

ori.w*CACRF_Clearl,dO 

dew $9E78, $0002 ;MOVEC DO.CACR 

bra.s cic_exit 

cic_040: dew $f4b8 ;CPUSHA(IC) 

cicexit: 



HARDWARE PROGRAMMING GUIDELINES 

If you find it necessary to program the hardware directly, then it is your responsibility to write code that will work 
correctly on the various models and configurations of the Amiga. Be sure to properly request and gain control of 
the hardware resources you are manipulating, and be especially careful in the following areas: 

Kickstart 2.0 uses the 8520 Complex Interface Adaptor (CIA) chips differently than 1 .3 did. To ensure 
compatibility, you must always ask for CIA access using the cia. resource AddlCRVectorQ and 
RemlCRVector() functions. Do not make assumptions about what the system might be using the CIA 
chips for. If you write directly to the CIA chip registers, do not expect system services such as the 
trackdisk device to function. If you are leaving the system up, do not read or write to the CIA Interrupt 
Control Registers directly; use the cia.resource AblelCRQ, and SetlCR() functions. Even if you are 
taking over the machine, do not assume the initial contents of any of the CIA registers or the state of any 
enabled interrupts. 
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All custom chip registers are Read-only or Write-only. Do not read Write-only registers, and do not write 
to Read-only registers. 

Never write data to, or interpret data from the unused bits or addresses in the custom chip space. To be 



software-compatible with future chip revisions, all undefined bits must be set to zeros on writes, and 
must be masked out on reads before interpreting the contents of the register 

Never write past the current end of custom chip space. Custom chips may be extended or enhanced to 
provide additional registers, or to use bits that are currently undefined in existing registers. 

Never read, write, or use any currently undefined address ranges or registers. The current and future 
usage of such areas is reserved by Commodore and is subject to change. 

Never assume that a hardware register will be initialized to any particular value. Different versions of the 
OS may leave registers set to different values. Check the Amiga Hardware Reference Manua\ to ensure 
that you are setting up all the registers that affect your code. 

ADDITIONAL ASSEMBLER DEVELOPMENT GUIDELINES 

If you are writing in assembly language there are some extra rules to keep in mind in addition to those listed 
above. 

Never use the TAS instruction on the Amiga. System DMA can conflict with this instruction's special 
indivisible read-modify-write cycle. 

System functions must be called with register A6 containing the library or device base. Libraries and 
devices assume A6 is valid at the time of any function call. Even if a particular function does not 
currently require its base register, you must provide it for compatibility with future system software 
releases. 

Except as noted, system library functions use registers DO, Dl, AO, and A1 as scratch registers and you 
must consider their former contents to be lost after a system library call. The contents of all other 
registers will be preserved. System functions that provide a result will return the result in DO. 

Never depend on processor condition codes after a system call. The caller must test the returned value 
before acting on a condition code. This is usually done with aTST or MOVE instruction. 
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1.3 Compatibility Issues 



This 3rd edition of the Amiga Technical Reference Series focuses on the Release 2 version of the Amiga 
operating system (Kickstart V2.04, V37). Release 2 of the operating system was first shipped on the Amiga 3000 
and now available as an upgrade kit for the Amiga 500 and Amiga 2000 models to replace the older 1 .3 (V34) 
operating system. Release 2 contains several new libraries and hundreds of new library functions and features to 
assist application writers. 

DESIGN DECISIONS 

The latest Amiga models, including all A3000's, are running Release 2. But many older Amigas are still running 
1 .3 at this time. Depending on your application and your market, you may choose to require the Release 2 
operating system as a minimum platform. This can be a reasonable requirement for vertical markets and 
professional applications. Release 2 can also be a reasonable requirement for new revisions of existing software 
products, since you could continue to ship the older 1 .3-compatible release in the same package. If you have 
made the decision to require Release 2, then you are free to take advantage of all of the new libraries and 
features that Release 2 provides. 

Throughout this latest edition of the Amiga Technical Reference Series, features, functions and libraries that are 
new for Release 2 are usually indicated by (V36) or (V37) in the description of the feature. Such features are not 
available on Amiga models that are running 13 (V34) or earlier versions of the OS. Unconditional use of Release 
2 functions will cause a program to fail when it is run on a machine with the 1.3 OS. It is very important to 
remember this when designing and writing your code. 



Developers of consumer-priced productivity, entertainment and utility software may not yet be ready to write 
applications that require Release 2, but even these developers can enhance their products by taking advantage 
of Release 2 while remaining 1.3 compatible. 

There are three basic methods that will allow you to take advantage of enhanced Release 2 features while 
remaining 1 .3 compatible: 

Transparent Release 2 Extensions 

Conditional Code 

Compatible Libraries 

Transparent Release 2 Extensions 

To provide Release 2 enhancements while remaining compatible with the older 1 .3 version of the OS, several 
familiar 1.3 system structures have been extended to include an optional pointer to additional information. The 
new extended versions of such structures are generally defined in the same include file as the original structure. 
These extended structures are passed to the same 1.3 system functions as the unextended structure (e.g., 
OpenWindowQ, OpenScreen, AddGadget, OpenDiskFont()). The existence of the extended information is 
signified by setting a new flag bit in the structure. (In one case, PROPNEWLOOK, only the flag bit itself is 
significant). These extensions are transparent to previous versions of the operating system. Only the Release 2 
operating system will recognize the bit and act on the extended information. 
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The table below lists the flag bit for each structure to specify that extended information is present. 



Original 


Extended 


Flag Field 


Flag Bit 


Defined In 


NewScreen 


ExtNewScreen 


Type 


NS EXTENDED 


<intuition/screens.h> 


NewWindow 


ExtNewWindow 


Flags 


WFLG NWEXTENDED 


<intuition/intuition.h> 


Gadget 


Gadget 


Flags 


GFLG STRINGEXTEND 


<intuition/intuition.h> 


Proplnfo 


Proplnfo 


Flags 


PROPNEWLOOK 


dntuition/intuition.h 


TextAttr 


TTextAttr 


tta_Style 


FSF TAGGED 


<graphics/text.h> 



Through the use of such extensions, applications can request special Release 2 features in a 1 .3-compatible 
manner. When the application is run on a Release 2 machine, the enhanced capabilities will be active. 

The enhancements available through these extensions include: 

Screen: Overscan, 3D Look (SAPens), public screens, PAL/NTSC, new modes 

Window: Autoadjust sizing, inner dimensions, menu help 

Gadget: Control of font, pens, and editing of string gadgets 

Proplnfo: Get 3D Look proportional gadgets when running under Release 2 

TTextAttr: Control width of scaled fonts 

Extensible longword arrays called Tagltem lists are used to specify the extended information for many of these 
structures. Tag lists provide an open-ended and backwards-compatible method of growing system structures by 
storing all new specifications in an extendible array of longwords pairs. 

Another transparent Release 2 extension is the diskfont library's ability to scale bitmap and outline fonts to 
arbitrary sizes and the availability of scalable outline fonts. Make sure that these new scalable fonts are available 
to your application by not setting the FPF_DESIGNED flag for AvailFontsQ or OpenDiskFontQ. Allow the user 
to create new font sizes by providing a way for her to manually enter the desired font size (the 1 .3 OS returns the 
closest size, Release 2 returns the requested size). 

See the Intuition and graphics library chapters, and the include file comments for additional information. See the 
"Utility Library" chapter for more information on Tagltems and tag lists. 



Conditional Code 

Conditional code provides a second way to take advantage of Release 2 enhancements in a 1 .3-compatible 
application. The basic idea is to add low overhead conditional code, based on library version, to make use of 
selected Release 2 features if they are available. There are some powerful and beneficial Release 2 features 
which are definitely worth conditional code. 

The control flow for such conditional code is always based on whether a particular version of a library is available. 
Failure of OpenLibrary() (i.e., return value of NULL) means that the library version requested is not available. 
The version number of a library that successfully opened can be checked by testing LibBase->lib Version. 
Always check for a version greater or equal 'to the version you need. 

Examples of conditional library checking code: 

/* Checking for presence of a new Release 2 library */ 
if ( AslBase = OpenLibrary ( "asl . library" , 37L) ) 

{ 

/* OK to use the ASL requester */ 

} 

else 

{ 

/* Must use a different method */ 

} 

/* Checking version of an existing library with new Release 2 features */ 
if (GfxBase->lib Version >= 37) { /* then allow new genlock modes */} 
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ASL Requesters 

The Release 2 ASL library provides standard file and font requesters. Allocation and use of an ASL requester can 
be handled by coding a simple subroutine to use the ASL requester if available. Otherwise use fallback code or a 
public domain requester. By now, many of you have probably coded your own requesters and you may be quite 
attached to them. In that case, at least give your users the option to use the ASL requester if they wish. By using 
the ASL requesters, you can provide a familiar interface to your users, gain the automatic benefit of all ASL file 
requester improvements, and stop maintaining your own requester code. 

DOS SystemQ, CreateNewProcQ, and CON: Enhancements 

If your program currently uses the 1 .3 AmigaDOS ExecuteQ or CreateProc() functions, then it is definitely worth 
conditional code to use their V37 replacements when running under Release 2. The System() function of 
Release 2 allows you to pass a command line to AmigaDOS as if it had been typed at a Shell window. System() 
can run synchronously with return values or asynchronously with automatic cleanup and it also sets up a proper 
stdio environment when passed a DOS filehandle for SYS Input and NULL for SYS Output. In combination with 
enhanced Release 2 CON: features, SystemQ can provide a suitable execution environment on either 
Workbench or a custom screen. The CreateNewProc() function provides additional control and ease in process 
creation. 

CON: input and output in custom Intuition screens and windows is now supported. New options in the Release 2 
console handler (CON:) provide the ability to open a CON: on any public Intuition screen, or to attach a CON: to 
an existing Intuition window. Additional options can add a close gadget or create an AUTO console window which 
will only open if accessed for read or write. Add conditional code to use these system-supported methods when 
running under Release 2 or later versions of the OS. Note that additional CON: option keywords can be easily 
removed under 1 .3 at runtime by terminating the CON: string with NULL after the window title. Consult The 
AmigaDOS Manual by Bantam Books for additional information on Release 2 CON: and DOS features. 

The Display Database 

The Release 2 graphics library and the Enhanced Chip Set (ECS) provide programmable display modes and 



enhanced genlock capabilities. Users with Release 2 and ECS may wish to use your application in one of the 
newer display modes. The Release 2 display database provides information on all of the display modes available 
with the user's machine and monitor. In addition, it provides useful information on the capabilities and aspect ratio 
of each mode (Displaylnfo.Resolution.x and to easily check if particular modes are available. 

The ExtNewScreen structure used with Intuition's OpenScreen() function allows you to specify new display 
modes with the SA_DisplaylD tag and a longword ModelD. The Release 2 graphics library VideoControl() 
function provides greatly enhanced genlock capabilities for machines with ECS and a genlock. Little conditional 
code is required to support these features. See the graphics library chapters and Autodocs for more information. 
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ARexx 

Add conditional ARexx capabilities to your program. ARexx is available on all Release 2 machines, and many 1 .3 
users have purchased ARexx separately. ARexx capability adds value to your product and allows users and 
vertical market developers to create custom and hybrid applications. Add the ability to control your application 
externally via ARexx, and internally via ARexx macros. Allow the user to execute ARexx scripts to control other 
programs, including the ability to pass information from your program to other applications. For more information 
on adding ARexx functionality to your application, see the Amiga Programmer's Guide to ARexx, a publication by 
Commodore Applications and Technical Support (CATS). Contact your local Commodore support organization 
for information on ordering this book. 

COMPATIBLE LIBRARIES 

Compatible libraries provide a third method for using Release 2 while remaining 1 .3-compatible. Some Release 2 
libraries are 1 .3-compatible and may be distributed with your product if you have a 1 .3 Workbench License and 
an amendment to distribute the additional library. 

IFFParse Library 

The new IFFParse library is compatible with both Release 2 and the 13 version of the OS. IFFParse is a run-time 
library which provides low level code for writing, reading, and parsing IFF files. Use of IFFParse library and the 
new IFF example code modules can significantly reduce your development and debugging time. In addition, the 
IFFParse code modules provide effortless handing of the clipboard device. See the "IFFParse Library" chapter in 
this book and the IFF Appendix of the Amiga ROM Kernel Reference Manual: Devices for additional information. 

Single Precision IEEE Math Libraries 

The Release 2 single precision IEEE math libraries are also compatible with 1.3. These libraries provide 
single-precision math functions that will use a math coprocessor if available. 

Third Party Compatible Libraries 

Developers of new code may wish to take advantage of the ease with which a user interface can be created 
using the Release 2 GadTools and ASL support libraries. These new libraries are not 1.3-compatible but there 
are some third party development efforts towards providing 1 .3-compatible versions of them. You may wish to 
explore this possibility. 
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Commodore Applications and Technical 
Support (CATS) 

Commodore maintains a technical support group dedicated to helping developers achieve their goals with the 
Amiga. Currently, technical support programs are available to meet the needs of both smaller, independent 
software developers and larger corporations. Subscriptions to Commodore's technical support publication, Amiga 
Mail, is available to anyone with an interest in the latest news, Commodore software and hardware changes, and 
tips for developers. 

To request an application for Commodore's developer support program, or a list of CATS technical publications 
send a self-addressed, stamped, 9" x 12" envelope to: 

CATS-lnformation 
1200 West Wilson Drive 
West Chester, PA 19380-4231 



Error Reports 



In a complex technical manual, errors are often found after publication. When errors in this manual are found, 
they will be corrected in a subsequent printing. Updates will be published in Amiga Mail, Commodore's technical 
support publication. 

Bug reports can be sent to Commodore electronically or by mail. Submitted reports must be clear, complete, and 
concise. Reports must include a telephone number and enough information so that the bug can be quickly 
verified from your report (i.e., please describe the bug and the steps that produced it). 

Amiga Software Engineering Group 

ATTN: BUG REPORTS 

Commodore Business Machines 

1200 Wilson Drive 

West Chester, PA 19380-4231 

USA 



BIX: amiga.com/bug. reports(Commercial developers) 
amiga.cert/bug.reports(Certified developers) 
amiga.dev/bugs(Others) 



USENET: bugs @ commodore. COM Or uunet ! cbmvax ! bugs 
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Chapter 2 

INTUITION AND THE AMIGA 

GRAPHICAL USER INTERFACE 



Intuition is the collective name for the function libraries, data structures and other elements needed to create a 
graphical interface for Amiga applications. Programmers use Intuition to perform user interface chores such as 
opening windows, managing menus, monitoring gadgets, reading the mouse position and so forth. 

Newcomers to the Amiga sometimes think of Intuition as the Amiga's operating system but it is not. Intuition is 
just one component that together with Exec, AmigaDOS, and other subsystems make up the whole operating 
system. Intuition is the most visible part of the operating system though since it provides the graphical user 
interface familiar to all Amiga users. 

About User Interfaces 

What is a user interface? This sweeping phrase covers all aspects of communication between the user and the 
computer. It includes the innermost mechanisms of the computer and rises to the height of defining a philosophy 
to guide the interaction between human and machine. Intuition is, above all else, a philosophy turned into 
software. 

Intuition's user interface philosophy is simple to describe: the interaction between the user and the computer 
should be consistent, simple and enjoyable; in a word, intuitive. Intuition supplies the tools needed to turn this 
philosophy into practice. 

Implicit in this philosophy is the idea that the user interface should be graphical. A graphical user interface, or 
GUI, is a visually oriented method of communicating with a computer in which system resources are represented 
by pictorial symbols that can be manipulated with a pointing device such as a mouse. Other types of user 
interfaces are possible such as the Amiga's Shell in which text commands are entered by typing them at the 
keyboard. For more information about user interfaces, refer to the Amiga User Interface Style Guide. 
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ELEMENTS OF THE AMIGA GRAPHICAL USER INTERFACE SYSTEM 

There is more to the Amiga user interface than Intuition. To build a complete user interface, application writers 
need to understand these other elements of the system software. 

Table 2-1 : Elements of the Amiga Graphical User Interface System 

System Element Purpose 

Intuition The main toolkit and function library for creating a graphical user interface 

(GUI) on the Amiga. 
Workbench The Amiga file system GUI in which icons represent applications and files. 

Preferences A family of editors and configuration files for setting Amiga system options 

BOO P S I Subsystem of Intuition that allows applications to add extensions to Intuition 

through object-oriented techniques (Release 2 only). 
Gadtools Library A support library for creating Intuition gadgets and menus (Release 2 only). 

ASL Library A support library for creating Intuition requesters (Release 2 only). 

Icon Library Main library for using Workbench icons. 

Workbench Library A support library for Workbench icons and menus (Release 2 only). 

Console Device An I/O support module which allows windows to be treated as text-based 

virtual terminals. 
Graphics Library The main library of rendering and drawing routines. 

Layers Library A support library that manages overlapping, rectangular drawing areas which 

Intuition uses for windows 



As you read about Intuition in the chapters to follow, you wil 
Amiga user interface in more detail. 



be introduced to each of these elements of the 



GOALS OF INTUITION 

Intuition was designed with two major goals in mind. The first is to give users a friendly and consistent 
environment to control the functions of the Amiga operating system and its applications. 

The second goal (the big one) is to give application designers a graphical user interface toolkit that manages all 
the complexities of sharing the system with other programs that may be running at the same time. Since the 
Amiga is a multitasking computer, many programs can reside in memory at the same time sharing the system's 
resources with one another. Programs take turns running so that, from the user's point of view, it appears that 
many programs are running simultaneously. 

On a multitasking computer like the Amiga, the user interface design must allow the user to control many 
programs with just one monitor, one keyboard, and one mouse. (Imagine driving many cars simultaneously with 
one steering wheel.) Intuition supplies the tools needed to solve this problem. 
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How the User Sees Intuition 



Intuition solves the problem of interacting with multiple programs by dividing the display up into multiple screens 
and overlapping windows so that each application has its own work area. The user sees the Amiga environment 
through these windows, each of which can represent a different task or application context. 

The user performs operations inside screens and windows with the mouse, a mechanical device that moves a 
pointer over the Amiga's display. The user moves the mouse to position the pointer on graphic symbols of various 
objects or actions. Buttons on the mouse are pressed to select or activate the item pointed to. 

The user can switch back and forth between different jobs, such as writing a document, drawing an illustration, 
printing text, or getting help from the system simply by moving from one window to another with the mouse. With 
the mouse, the user can also change the shape and size of application windows, move them around on the 
screen, overlap them, bring a window to the foreground, and send a window to the background. By changing the 
arrangement of the windows, the user selects which information is visible and which application to work with next. 
(Screens may also be moved up or down in the display, and they can be moved in front of or behind other 
screens.) 
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Figure 2-1 : The Workbench Screen With WLndows 



WORKBENCH AND PREFERENCES 

Normally, the Workbench screen (shown above) is the first screen the user sees upon booting the Amiga. 
Workbench is a special program supplied with every Amiga that gives the user a friendly and consistent graphic 
interface to the file system. It's the default environment the user starts out with. 

In Workbench, disks, directories, files and other objects are symbolized by small pictures called icons which can 
be manipulated with the mouse. For instance, a program file can be executed by pointing to its icon with the 
mouse and double-clicking the left mouse button. The Workbench screen is automatically set up by Intuition and 
can be easily shared, so many application programs use it too. 
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User control of the OS is also supported through Preferences. Preferences is a family of editors and associated 
configuration files that allow the user to control the basic set up of the operating system. For example Printer 
Preferences sets up all the printer options. 

Workbench, together with Preferences, gives the user an easy way to control the OS and launch applications. 
These programs are built with the same Intuition tools available to application programmers giving the whole 
Amiga system an integrated look and feel. Workbench and Preferences are important components of the Amiga 
graphic user interface system and are discussed in greater detail in later chapters. 

INTUITION'S 3D LOOK 

The Amiga operating system comes in different versions. The latest version, Release 2, contains significant 
improvements in the appearance of the Intuition graphical user interface, usually referred to as the 3D Loo/cof 
Intuition. 
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Figure 2-2: An E*ample of tlw 3D Look of Intuition 



In the new 3D look of Intuition, objects are drawn so that light appears to come from the upper left of the display 
with shadows cast to the lower right. Using light and shadow gives the illusion of depth so that images appear to 
stand out or recede from the display. By convention, an image with a raised appearance indicates an object that 
is available for use or modifiable. An image with a recessed appearance indicates an object that is unmodifiable, 
or for display purposes only. Applications should follow the same conventions. 

Release 2 has other improvements over 1 .3 (V34) and earlier versions of the operating system. Among these are 
new display resolutions, display sizes, and new function libraries to support Intuition. Most of the examples listed 
in this book assume Release 2. Where appropriate, the old 1 .3 methods are also described. 
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How an Application Sees Intuition 

Intuition is organized as a library of over 100 functions. Before using an Intuition function you must first open the 
Intuition library. (In general, you must always open a library before you can call the functions of that library. See 
Chapter 1 , "Introduction to Amiga System Libraries".) 

COMPONENTS OF INTUITION 

The types of data objects that the Intuition library functions create and control fall into six broad categories. These 
arc the main components an application uses to build and operate a graphic user interface on the Amiga. 

Table 2-2: GUI Components of Intuition 

Screens The display environment. Sets the resolution and number of colors. 

Windows A graphic rectangle within a screen representing a working context. 

Menus A list of choices displayed at the top of a screen that can be selected with the 

mouse. 
Gadgets A control symbolized by a graphic image that can be operated with the mouse or 

keyboard. 
Requesters Sub-windows for confirming actions, accessing files and other special options. Input 

events Mouse, keyboard or other input activity. 

SCREENS AND WINDOWS 

As mentioned earlier, Intuition allows multiple programs to share the display by managing a system of multiple 
screens and overlapping windows. A screen sets up the display environment and forms the background that 
application windows operate in. A window is simply a graphic rectangle that represents a work context. Each 
screen can have many windows on it. 

Multiple screens and windows give each application its own separate visual context so that many programs can 
output graphics and text to the display at the same time without interfering with one another. Intuition (using the 
layers library) handles all the details of clipping graphics so they stay inside window bounds and remembering 
graphics that go temporarily out of sight when the user rearranges windows. 

The keyboard and mouse are shared among applications through a simpler technique: only one application 
window at a time can have the input focus. Hence, Intuition ensures that only one window, called the active 
window gets to know about keyboard, mouse and other types of input activity. 

Each application window is like a virtual termina\ or console. Your program will seem to have the entire machine 
and display to itself. It can send text and graphics to its terminal window, and ask for input from any number of 
sources, ignoring the fact that other programs may be performing these same operations. Intuition handles all the 
housekeeping. In fact, your program can open several of these virtual terminals and treat each one as if it were 
the only program running on the machine. Intuition will keep track of all the activity and make sure commands 
and data are dispatched to the right place. 
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GADGETS, MENUS AND REQUESTERS 

Intuition screens and windows provide an orderly way for multiple programs to share the display and input 
devices. Each application also needs a method for the user to send commands to it and select its options. 
Intuition supplies gadgets, menus and requesters for this purpose. 

Gadgets 

A gadget is an application control symbolized by a graphic image that can be operated with the mouse or 
keyboard. The imagery used for a gadget could look like a switch, a knob, a button, or just about anything. 
Intuition supplies some pre-fabricated gadgets, called system gadgets, for controlling window and screen 
arrangements. Other gadget types allow the user to select colors, enter text or numbers, and perform other 
simple operations. 
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figure 2-3: An Intuition Window with Gadgats 



Most of the user's input for a typical Intuition application will be obtained with gadgets. Gadgets are discussed in 
detail in Chapter 5, "Intuition Gadgets". Additional information on programming gadgets for Release 2 of the 
operating system can be found in Chapter 15, "GadTools Library". 
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Menus 



Intuition also supplies a menu system for accepting commands and options from the user. A menu is a list of 
choices displayed at the top of the screen from which the user can select with the mouse. Each screen has one 
menu bar that all application windows operating on the screen share. Whichever window is active controls what 
appears in the menu bar. 
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Figure £-4: An Intuition Menu 

The current set of menu choices can always be brought into view by pressing the right mouse button (the menu 
button) thus providing the user with a familiar landmark even in unfamiliar applications. Menus allow the user to 
browse through the possible set of actions that can be performed giving an outline-like overview of the functions 
offered by a program. 

Menus are discussed in detail in Chapter 6, "Intuition Menus". Additional information on programming menus for 
Release 2 of the operating system can be found in Chapter 15, "GadTools Library". 
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Requesters 

Gadgets and menus do much of the work of getting 
commands and option choices from the user. 
Sometimes though, an application needs to get further 
information from a user in response to a command 
which has already been initiated. In that case, a 
requester can be used. A requesters a temporary 
subwindow, usually containing several gadgets, used to 
confirm actions, access files, or adjust the special 
options of a command the user has already given. 

Requesters are discussed in detail in Chapter 7, 
"Intuition Requesters and Alerts". Additional information 
on programming requesters for Release 2 of the system 
can be found in Chapter 16, "ASL Library". 
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Figure 2-5: An Intuition Requester 



The Intuition Input Event Loop 

Once an application has set up the appropriate screen, window, gadgets menus and requesters, it waits for the 
user to do something. Intuition can notify an application whenever user activity occurs by sending a message. 
The message is simply a pointer to some memory owned by Intuition that contains an I ntui Message data 
structure describing the user activity that occurred. 

To wait for user activity or other events, the Exec library provides a special function named Wait(). The Exec 
Wait() function suspends your task allowing other applications or system tasks to run while your application is 
waiting for input or events from Intuition and other sources. 

Thus, the basic outline for any Intuition program is: 

Set up the window, screen and any required gadgets, menus or requesters. 

Wait() for a message from Intuition about user activity or other events. 

Copy needed data from the message and tell Intuition you received it by replying. 

Look at the data and take the appropriate action. 

Repeat until the user wants to quit. 

These steps, sometimes referred to as the Intuition input event loop are basically the same for any Intuition 
application. 
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As you might expect, Intuition can send a message to your application whenever the user presses a key on the 
keyboard or moves the mouse. Other types of input events Intuition will notify you about include gadget hits, 
menu item selection, time elapsing, disk insertion, disk removal, and window rearrangement. 

Gadgets, menus, requesters are the nuts and bolts of the Intuition GUI toolkit. Much of the code in an application 
that uses Intuition deals with the set up and operation of these important data objects. No matter how simple, 
complex, or fanciful your program design, it will fit within the basic Intuition framework of windows and screens, 
gadgets, menus and requesters. The users of the Amiga understand these basic Intuition elements and trust that 
the building blocks remain constant. This consistency ensures that a well-designed program will be 
understandable to the naive user as well as to the sophisticate. 



A Simple Intuition Program 



The sample Intuition program that follows shows all of the basic requirements for an Intuition application. There 
are three important points: 

You must open the Intuition library before you can use the Intuition functions. Certain languages such 
as C require the pointer W the Intuition library to be assigned to a variable called IntuitionBase (see 
Chapter 1 for more about this). 

When you set up a window, you also specify the events that you want to know about. If the user 
performs some activity that triggers one of the events you specified, Intuition signals you and sends a 
message. The message is a pointer to an IntuiMessage data structure that describes the event in more 
detail. Messages about Intuition events are sent to a MsgPort structure which queues up the messages 
for you in a linked list so that you may respond to them at your convenience. 

Resources must be returned to the system. In this case, any windows, screens or libraries that were 
opened are closed before exiting. 

EXAMPLE INTUITION EVENT LOOP 

The Intuition event loop used in the example is very simple. The example first sets up a custom screen, opens a 
window on it, then waits for Intuition to send messages about user input with the following event loop: 

winsignal = 1L << windowl->UserPort->mp_SigBit ; /* window signal */ 



signalmask = winsignal; /* example only waits for window events */ 
while ( ! done) 

{ 

signals = Wait (signalmask) ; 
if (signals s winsignal) 

done = handlelDCMP (windowl) ; 
} 

Intuition sends messages about user activity to a special port known as the IDCMP. Each window can have its 
own IDCMP (in the code above the IDCMP is windowl ->UserPort). To wait for event messages to arrive at the 
IDCMP port, the example code calls the Exec Wait() function. It then processes and replies to any event 
messages that it gets in a subroutine named handlelDCMP(). For this example, the only event Intuition will report 
is the close window event. When the example detects this event, it closes the window, closes the screen, closes 
the Intuition library and exits. Event loops similar to this one are used in Intuition examples throughout this book. 
For more information about IDCMP and user input, see the chapters on "Intuition Windows" and "Intuition Input 
and Output". 
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INTUITION EXAMPLE (V36 AND LATER) 

This example shows a simple Intuition program that works with Release 2 (V36) and later versions of the Amiga 
operating system. 

/* easyintuition37 . c -- Simple Intuition program for V37 */ 
/* (Release 2) and later versions of the operating system. */ 
/* Compiled with Lattice C v5 . 04 : lc -L easyintuition37 . c */ 

#include <exec/types . h> /* The Amiga data types file. */ 

#include <intuition/intuition.h> /* Intuition data structures, etc. */ 
#include <graphics/displayinf o . h> /* Release 2 Amiga display mode ID'S */ 
#include <libraries/dos . h> /* Official return codes defined here */ 

#include <clib/exec_protos . h> /* Exec function prototypes */ 
#include <clib/intuition protos.h> /* Intuition function prototypes */ 

/* Force use of new variable names to help prevent errors */ 

#define INTUI_V3e_NAMES_ONLY 

#ifdef LATTICE /* Disable Ctrl-C handling in SAS/C */ 

int CXBRK(void) { return ( )} ; 

void chkabort (void) [return;} 

#endif 

/* Use lowest non-obsolete version that supplies the functions needed. */ 
#define INTUITION REV 37 

/* Declare the prototypes of our own functions. Prototypes for system */ 
/* functions are declared in the header files in the clib directory. */ 
VOID cleanExit ( struct Screen *, struct Window *, LONG ) ; 
BOOL handlelDCMP ( struct Window *) ; 

struct Library *IntuitionBase = NULL; 

/* Position and sizes for our window */ 

#define WIN_LEFTEDGE 2 

#define WINJTOPEDGE 2 

#define WIN_WIDTH 400 

#define WIN_MINWIDTH 8 

#define WIN_HEIGHT 150 

#define WIN MINHEIGHT 2 

VOID main (int argc, char *argv[] } 
{ /* Declare variables here */ 

ULONG signalmask, winsignal, signals; 
BOOL done = FALSE; 
UWORD pens [] = (~0) ; 



struct Screen *screenl = NULL; 
struct Window *windowl = NULL; 

/* Open the Intuition Library */ 

IntuitionBase = OpenLibraryt "intuition. library" , INTUITION REV ) ; 

if (IntuitionBase == NULL) 

cleanExit (screenl, windowl, RETURN_WARN) ; 

/* Open any other required libraries and make */ 
/* any assignments that were postponed above */ 

/* Open the screen */ 

screenl = OpenScreenTags (NULL, 

SA_Pens, (ULONG)pens, 

SA_DisplayID, HIRES_KEY, 
SA_Depth, 2, 

SA_Title, (ULONG) "Our Screen", 
TAG DONE) ; 

if (screenl == NULL) 

cleanExit (screenl, windowl, RETURN_WARN) ; 

/*. . and open the window */ 
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windowl = OpenWindowTags (NULL, /* Specify window dimensions and limits */ 

WA_Left, WIN_LEFTEDGE, 
WA_Top , WIN_TOPEDGE , 
WA_Width, WIN_WIDTH, 
WA_Heiqht , WIN_HEIGHT, 
WA_MinWidth, WIN_MINWIDTH, 
WA_MinHeight, WIN_MINHEIGHT, 
WA_MaxWidth, ~0, 
WA_MaxHeight, -0, 

/* Specify the system qadgets we want */ 
WA_CloseGadget, TRUE, 
WA_SlzeGadget, TRUE, 
WA_DepthGadget , TRUE , 
WA_DragBar, TRUE, 

/* Specify other attributes */ 

WA_Ac tivate, TRUE, 
WA NoCareRefresh.TRUE, 



know about */ 



screen . . . */ 



/* Specify the events we want to 
WA_IDCMP, IDCMP_CLOSEWINDOW, 

/* Attach the window to the open 



WA_CustomScreen, screenl, 

WA_Title, "EasyWindow" , 

WA_ScreenTitle, "Our Screen - EasyWindow is Active", 

TAG_DONE) ; 

if (windowl == NULL) 

cleanExit (screenl, windowl, RETURN WARN) ; 

/* Set up the signals for the events we want to hear about ... */ 

winsignal = 1L << windowl ->UserPort->mp SigBit; /* window IDCMP */ 

signalmask = winsignal; /* we are only waiting on IDCMP events •/ 

/* Here's the main input event loop where we wait for events. */ 
/* We have asked Intuition to send us CLOSEWINDOW IDCMP events */ 
/* Exec will wake us if any event we are waiting for occurs. */ 
while ( ! done) 

{ 

signals = Wait (signalmask) ; 

/* An event occurred - now act on the siqnal(s) we received.*/ 



/* We were only waiting on one signal (winsignal) in our */ 

/* signalmask, so we actually know we received winsignal. */ 
if (signals s winsignal) 

done = handlelDCMP (windowl) ; /* done if close gadget */ 

} 

cleanExit (screenl, windowl, RETURN OK); /* Exit the program */ 

} 

BOOL handlelDCMP (struct Window *win) 

{ 

BOOL done = FALSE; 

struct IntuiMessage 'message = NULL; 

ULONG class; 

/* Examine pending messages */ 

while (message = (struct IntuiMessage *) GetMsg (win->UserPort) ) 

{ 

class = message- >Class; /• get all data we need from message */ 

/* When we're through with a message, reply */ 
ReplyMsg( (struct Message *)message); 

/* See what events occurred */ 
switch (class) 

{ 

case IDCMP_CLOSEWINDOW: 
done = TRUE; 
break; 

default : 

break; 

} 

return (done) ; 



} 
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VOID cleanExit (struct Screen *scrn, struct Window *wind, LONG returnValue) 

{ 

/* Close things in the reverse order of opening */ 
if (wind) 

CloseWindow (wind) ; 

/* Close window if opened */ 
if (scrn) 

CloseScreen (scrn) ; /* Close screen if opened */ 

/* Close the library, and then exit */ 
if (IntuitionBase) 

CloseLibrary ( IntuitionBase ); 
exit (returnValue) ; 



INTUITION EXAMPLE (ALL VERSIONS) 

Here's the same example as above written for both Release 2 and earlier versions of the operating system. The 
main difference here is that this example avoids using any new Release 2 functions, but does pass extended 
structures to the older Intuition functions so that some new Release 2 features may be accessed in a 
backward-compatible manner. 

/* easyintuition, c Simple backward-compatible V37 Intuition example */ 

/**/ 

/* This example uses extended structures with the pre-V37 OpenScreen ( ) */ 
/* and OpenWindow ( ) functions to compatibly open an Intuition display. */ 
/* Enhanced V37 options specified via tags are ignored on 1.3 systems. */ 
/* Compiled with Lattice C V5.10: lc -L easyintuition. c */ 



/* Force use of new variable names to help prevent errors */ 
#define INTUI_V3 6_NAMES_ONLY 

#include <exec/types . h> /* The Amiga data types file. */ 

#include <intuition/intuition.h> /* Intuition data strucutres, etc. */ 
#include <libraries/dos . h> /* Official return codes defined here */ 



#include <clib/exec_protos . h> 
#include <clib/intuition protos.h> 



/* Exec function prototypes 

/* Intuition function prototypes 



#ifdef LATTICE /* Disable Ctrl-C handling in SAS/C */ 
int CXBRK(void) { return ( ) ; } 
void chkabort (void) (return;) 
#endif 

/* Use lowest non-obsolete version that supplies the functions needed. */ 
#define INTUITION REV 33L 

/* Declare the prototypes of our own functions. Prototypes for system */ 
/* functions are declared in the header files in the clib directory */ 
VOID cleanExit ( struct Screen *, struct Window *, LONG ) ; 
BOOL handlelDCMP ( struct Window *) ; 

struct Library *IntuitionHase = NULL; 

/* We can specify that we want the V37-compatible 3D look when 

** running under V3 7 by adding an SA Pens tag. */ 

WORD pens [ } = {~0}; /* empty pen array to get default 3D look */ 

struct Tagltem ourscreentags [] = 

( 

(SA_Pens, ULONG)pens ) , 

( TAG DONE ) 



/" ExtNewScreen is an extended NewScreen structure. 

* NS_EXTENDED flags that there is a tag pointer to additional 

* tag information at the end of this structure. The tags will 

* be parsed by Release 2 but ignored by earlier OS versions. */ 
struct ExtNewScreen fullHires = 

{ 



, 



/" LeftEdge must be zero prior to Release 



0, 

640, 

STDSCREENHEIGHT, 

2, 

0,1, 



/* TopEdge */ 

/* Width (high-resolution) */ 
/* Height (non-interlace) */ 

/* Depth (4 colors will be available) */ 
/* Default DetailPen and BlockPen */ 
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}; 



HIRES, 

CUSTOMSCREEN | NS_EXTENDED , 

NULL, 

"Our Screen", 

NULL, 

NULL, 

ourscreentags 



/* the high-resolution display mode */ 

/* the screen type */ 

/* no special font */ 

/* the screen title */ 

/* no custom screen gadgets (not supported) */ 

/* no CustomBitMap */ 

/* tags for additional V37 features */ 



/* Position and sizes for our window */ 
#define WIN_LEFTEDGE 2 
#define WINJTOPEDGE 2 
#define WIN_WIDTH 400 
#define WIN_MINWIDTH 8 
#define WIN_HEIGHT 150 
#define WIN MINHEIGHT 2 



/* Under V37, we'll get a special screen title when our window is active */ 
UBYTE activetitle [] = {"Our Screen - EasyWindow is Active"}; 



struct Tagltem ourwindowtags [] = 

{ 

(WA_ScreenTitle, (ULONG) kactivetitle [0] ), 
( TAGJDONE ) 

}; 

/* ExtNewWindow is an extended NewWindow structure. 

* NW_EXTENDED indicates that there is a tag pointer to additional tag 

* information at the end of this structure. The tags will be parsed 

* by Release 2 but ignored by earlier OS versions. */ 
struct ExtNewWindow easyWindow = 

{ 

WIN_LEFTEDGE , 

WIN_TOPEDGE , 

WIN_WIDTH, 

WIN_HEIGHT, 

-1,-1, /* Means use the screen's Detail and Block pens */ 

IDCMP CLOSEWINDOW, /* This field specifies the events we want to get */ 

/* These flags specify system gadgets and other window attributes */ 
/* including the EXTENDED flag which flags this as an ExtNewWindow */ 

WFLG_CLOSEGADGET | WFLG_SMART_REFRESH | WFLG_ACTIVATE | WFLG_DRAGBAR | WFLG_DEPTHGADGET 
WFLG_SIZEGADGET | WFLG_NOCAREREFRESH | WFLG_NW_EXTENDED, 

NULL, /* Pointer to the first gadget */ 

NULL, /* No checkmark. */ 

"EasyWindow", /* Window title. */ 

NULL, /* Attach a screen later. */ 

NULL, /* Let Intuition set up BitMap */ 

WIN_MINWIDTH, /* Minimum width. */ 

WIN_MINHEIGHT, /* Minimum height. */ 

-1, /* Maximum width (screen size) */ 

-1, /* Maximum height (screen size) */ 

CUSTOMSCREEN, /* A screen of our own.*/ 

ourwindowtags /* tags for additional V37 features */ 

} ; 

VOID main(int argc, char *argv[]) 

{ 

/* Declare variables here */ 

ULONG signalmask, winsignal, signals; 

BOOL done = FALSE; 

struct Screen *screenl = NULL; 

struct Window *windowl = NULL; 

/* Open Intuition Library. NOTE - We are accepting version 33 (1.2) 

* or higher because we are opening our display in a compatible manner. 

* However - If you add to this example, do NOT use any NEW V37 
* functions unless IntuitionBase->lib Version is >= 37 */ 

IntuitionBase = OpenLibraryt "intuition. library" , INTUITION_REV ) ; 
if (IntuitionBase == NULL) 

cleanExit (screenl, windowl , RETURN WARN) ; 
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/* Open any other required libraries and make */ 
/* any assignments that were postponed above */ 

/* Open the screen */ 

screenl = OpenScreen (kfullHires) ; 

if (screenl == NULL) 

cleanExit (screenl, windowl, RETURN_WARN) ; 

/* Attach the window to the open screen ... */ 
easyWindow. Screen = screenl; 

/* . . and open the window */ 
windowl = OpenWindow (seasyWindow) ; 



} 



if (windowl == NULL) 

cleanExit (screenl, windowl, RETURN_WARN) ; 

/* Set up the signals for the events we want to hear about ... */ 
winsignal = 1L << windowl - >UserPort - >mp_SigBit ; 
/* window IDCMP */ 
signalmask = winsignal; 
/* we will only wait on IDCMP events */ 

/* Here's the main input event loop where we wait for events. */ 
/* We have asked Intuition to send us CLOSEWINDOW_IDCMP events */ 
/* Exec will wake us if any event we are waiting for occurs. */ 
whilel ( ! done) 

{ 

signals = Wait (signalmask) ; 

/* An event occurred - now act on the signal (s) we received.*/ 

/* We were only waitinq on one signal (winsignal) in our */ 

/* signalmask, so we actually know we received winsignal. */ 
if (signals & winsignal) 

done = handlelDCMP (windowl) ; /* done if close qadget */ 

} 

cleanExit (screenl, windowl, RETURN OK); /* Exit the program */ ) 



BOOL handlelDCMP ( struct Window *win ) 

{ 

BOOL done = FALSE; 

struct IntuiMessage 'message; 

ULONG class; 

/* Examine pending messages */ 

while ( message = (struct IntuiMessage *) GetMsg (win->UserPort) ) 

{ 

class = message- >Class; /* get all data we need from message */ 

/* When we're through with a message, reply */ 
ReplyMsg( (struct Message *)message); 

/* See what events occurred */ 
switch ( class ) 

{ 

case IDCMP_CLOSEWINDOW: 

done = TRUE ; 

break; 

default : 
break; 
} 
} 
return (done) ; 

} 

VOID cleanExit ( struct Screen *scrn, struct Window *wind, LONG returnValue ) 

{ 

/* Close things in the reverse order of opening */ 
if (wind) 

CloseWindow( wind ) ; /* Close window if opened */ 

if (scrn) 

CloseScreen( scrn ) ; /* Close screen if opened */ 

/* Close the library, and then exit */ 
if (IntuitionBase) 

CloseLibrary ( IntuitionBase ) ; 
exit (returnValue) ; 
} 
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Chapter 3 
INTUITION SCREENS 



Intuition screens are the basis of any display Intuition can make. Screens determine the fundamental 
characteristics of the display such as the resolution and palette and they set up the environment for multiple, 
overlapping windows that makes it possible for each application to have its own separate visual context. This 
chapter shows how to use existing screens and how to create new screens. 



Types of Screens 



Screens are important because they determine the basic resolution and maximum number of colors in the 
display. Once a screen is set up, these attributes cannot be changed so any graphics work done on a given 
screen is restricted to that screen's resolution and number of colors. Hence, the type of screen used is a basic 
design decision. 

With Intuition screens, a video display can be created in any one of the many Amiga display modes. The basic 
parameters of the video display such as resolution, total size, frame rate, genlock compatibility, support of screen 
movement and number of colors are defined by these modes. There are currently four basic modes available on 
all Amiga models. These basic modes work with conventional monitors (15 kHz scan rate) and older versions of 
the operating system. 



Basic Amiga 


Resolution 




Maximum 


Supports 


Display Modes 


NTSC 


PAL 


Colors 


HAM/EHB 


Lores 


320x200 


320x256 


32 of 4096 


Yes 


Lores- Interlaced 


320x400 


320x512 


32 of 4096 


Yes 


Hires 


640x200 


640x256 


16 of 4096 


No 


Hires-Interlaced 


640x400 


640x512 


16 of 4096 


No 



*HAM and EHB modes provide for additional colors with some restrictions. 

Table 3-1 : Basic Amiga Display Modes 

With Release 2 of the operating system, many other display modes are available (these usually require a special 
monitor or ECS). All these display modes, including the specialized modes, are integrated through the graphics 
library display database. See the "Graphics Primitives" chapter for a complete list of all Amiga display modes. 
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MULTIPLE SCREENS 

All Intuition display objects (such as windows and menus) take graphical characteristics from the screen. These 
objects are restricted to the same resolution and maximum number of colors as the screen they operate in. Other 
characteristics such as the palette, pens and fonts are inherited from the screen (but may be changed on a case 
by case basis). 

This is not too much of a restriction because the Amiga can maintain multiple screens in memory at the same 
time. In other words, one application can use a high resolution screen (with 1 6 colors) while another application 
uses a low resolution screen (with 32 colors) at the same time. Screens typically take up the entire viewing area 



so only one is usually visible. But screens can be moved up and down or rearranged allowing the user 
application) to move between screens easily. 



or 



PUBLIC SCREENS AND CUSTOM SCREENS 

An application may choose to use an existing screen or to create its own screen. For instance, the normal Amiga 
start-up process opens the Workbench screen (Workbench is the Amiga's default user interface). Any application 
is free to use the Workbench screen instead of opening a new one. Screens that can be shared this way are 
called public screens. 

Public screens are a new feature of Release 2 (V36). In older versions of the OS, only the Workbench screen 
could be shared. Now any screen may be set up as a public screen so that other applications may use it. 

The use of an existing public screen, like the Workbench screen, requires little effort by the application and does 
not use up any memory. However, using Workbench or another existing public screen means some flexibility is 
lost; the resolution, maximum number of colors and other attributes are already set. If the application cannot 
function under these limitations, it may open its own custom screen. 

Custom screens allow for complete control of the display space so an application can get exactly the kind of 
display it wants. However, since creating a new, custom screen uses up memory, they should only be used when 
there are no suitable public screens available. 

Owners of a custom screen can keep their screen private, or they may allow other applications to share their 
screen by registering the screen with the operating system as a public screen. See the section on "Public Screen 
Functions" later in this chapter for more about public screens and Workbench. 
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Figure 3-1: An Intuition Screen (Workbench) 



SCREEN COMPONENTS 

Screens have very little visual impact, they simply provide a resolution specific area to place other objects such 
as windows and menus. Screens have no borders. Only the title bar marks the screen limits (specifying the left 
and top edges, and the width of the screen), and the title bar may be hidden, or obscured by graphics or 
windows. 

The title bar also serves as the menu bar when the user presses the menu button on the mouse bar area is 
shared by all applications operating within the screen. 
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Within the title bar, there are two gadgets: a screen drag gadget and a depth-arrangement gadget. The screen 
drag gadget allows the screen to be moved up and down. The depth-arrangement gadget allows the screen to be 
placed in front or behind all other screens. 

Screens are always rectangular, and the areas at the sides and bottom of the display that are not within the 
screen's limits are filled with the background color. The area above all visible screens is filled with the 
background color of the highest screen. These areas surrounding the screen (normally unused) are known as the 
overscan area. The Amiga display system allows the overscan area to be used for graphics under special 
circumstances (see the section on "Overscan and the Display Clip" later in this chapter). 



Screen Data Structures 



The Amiga uses color registers and bitplane organization as its internal representation of display data. Screens 
require a color table and display raster memory for each bitplane. This is the memory where imagery is rendered 
and later translated by the hardware into the actual video display. This information is contained in data structures 
from the Amiga's graphics library. 

A ViewPort is the main data structure used by the graphics library to represent a screen. Pointers to each of the 
screen's bitplanes are stored in the graphics library BitMap structure. Color table information is stored in a 
graphics structure called a ColorMap. And the screen's drawing and font information is stored in the RastPort 
structure. 

The graphics RastPort structure is a general-purpose handle that the graphics library uses for drawing 
operations. Many Intuition drawing functions also take a RastPort address as a parameter. This makes sense 
since the RastPort structure contains drawing variables as well as a pointer to the BitMap telling where to draw. 
See the "Graphics Primitives" chapter for more information on these structures and how they are used. 
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THE INTUITION SCREEN DATA STRUCTURE 

The structures mentioned above are unified along with other information in Intuition's Screen data structure 
defined in the include file <intuition/screens.h>. Notice that the Screen structure contains instances of a 
ViewPort, RastPort and BitMap. 

struct Screen 

{ 

struct Screen *NextScreen; 

struct Window *FirstWindow; 

WORD LeftEdge, TopEdge , Width, Height; 

WORD MouseY, MouseX; 

UWORD Flags; 

UBYTE *Title, *DefaultTitle; 

BYTE BarHeight, BarVBorder, BarHBorder, MenuVBorder, MenuHBorder; 



BYTE WBorTop, WBorLeft, WBorRight , WBorBottom; 

struct TextAttr *Font; 

struct Viewport Viewport; 

struct RastPort RastPort; 

struct BitMap BitMap; 

struct Layer_Info Layerlnfo; 

struct Gadget *FirstGadget ; 

UBYTE DetailPen, BlockPen; 

UWORD SaveColorO; 

struct Layer *BarLayer; 

UBYTE *ExtData, *UserData; 



} 



In general, applications don't need to access the fields in the Screen structure directly; they use Intuition 
functions to manipulate the screen instead. Likewise, applications do not set up the Screen themselves; they use 
one of the OpenScreen() calls (see below). Here is a description of some of the more interesting members of the 
Screen structure (it is not meant to be a complete description of all the fields). 

LeftEdge, TopEdge 

The LeftEdge and TopEdge variables give the position of the screen relative to the upper left corner of 
the monitor's visible display (as set by the user in the Overscan preferences editor). If it is positioned 
down or to the right, the values are positive. If the screen is positioned up or to the left, the values are 
negative. The values are in screen resolution pixels. In systems prior to V36, LeftEdge positioning is 
ignored and negative TopEdge positions are illegal. 

The screen position may be set when the screen is opened or later by calling the MoveScreen() 
function. Note that the screen's actual display position may not exactly equal the coordinates given in 
the LeftEdge and TopEdge fields of the Screen structure. This can cause a window which is opened in 
the visible part of the screen to be incorrectly positioned by a few pixels in each direction. This 
complication is due to hardware constraints that limit the fineness of screen positioning. For instance, 
high resolution screens can only be positioned in low resolution pixel coordinates, yet the values in the 
LeftEdge and TopEdge use high resolution pixel coordinates. So when the screen is displayed, its 
position is rounded to a position available for the monitor. 

MouseX, Mouse Y 

Position of the mouse with respect to the upper left corner of the screen. 

ViewPort, RastPort, BitMap, Layerlnfo 

Actual instances of the graphics library data structures associated with this screen (not pointers to 
structures) or normal use of custom screens, these structures may be ignored. 

BarLayer 

A pointer to the Layer structure for the screen's title bar. 
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WBorTop, WBorLeft, WBorRight, WBorBottom 

Window border values, see the "Intuition Windows" chapter for information on pre-calculating the size of 
window borders for windows that open in this screen. 



Font 



The default screen font, this can be used to pre-calculate the size of the window borders for windows 
that open in this screen. 



UserData 

Free for application use. 

Other Screen structure members provide information on the tide bar layer, and attributes of menus and windows 
opened in the screen. Of particular interest are the values that allow precalculation of window border size. These 
variables will be discussed in the chapter "Intuition Windows". 



OTHER SCREEN DATA STRUCTURES 

In addition to the Screen structure, Intuition uses some other supporting structures defined in the include file 
<\ntuition/screens.h> and in <utility/tagitems.h>. (See the Amiga ROM Kernel Reference Manual: Includes and 
Autodocs for a complete listing.) 



Table 3-2: Data Structures Used with Intuition Screens 



Structure Name 
Screen 

Drawlnfo 

Tagltem 

NewScreen 
ExtNewScreen 



Description 

Main Intuition structure that defines a screen (see 

above) 

Holds the screen's pen, font and aspect data for 

Intuition 

General purpose parameter structure used to set up 

screens in V36 

Parameter structure used to create a screen in V34 

An extension to the NewScreen structure used in 

V37 for backward compatibility with older systems 



Defined in Include File 

< intuition/screens. h> 

<\ntuition/screens. h> 

< utility/tagitem. h> 

<\ntuition/screens. h> 

< intuition/screens. h> 



As previously mentioned, there is an Intuition Screen structure (and a corresponding graphics ViewPort) for 
every screen in memory. Under Release 2, whenever a new screen is created, Intuition also creates an auxiliary 
data structure called a Drawlnfo. 

The Drawlnfo structure is similar to a RastPort in that it holds drawing information. But where a RastPort is 
used at the lower graphics level, the Drawlnfo structure is used at the higher Intuition level. Specifically, 
Drawlnfo contains data needed to support the New Look of Intuition in Release 2. (See the section below, 
"Drawlnfo and the 3D Look", for more information.) 

Another new feature of Release 2 is tag items. A Tagltem is a general purpose parameter structure used to pass 
arguments to many of the functions in the Release 2 system software. Each tag consists of a LONG tag ID 
(ti_Tag) and a LONG tag data value (ti_Data). With screens, tag items are used to describe the attributes an 
application wants for a new, custom screen. Tag items replace the NewScreen structure, the set of parameters 
used in older versions of the OS to set up a screen. 



Intuition 



Table 3-3: Custom Screen Functions 



OpenScreenTags() 
OpenScreenTag List() 
OpenScreenQ 



CloseScreenQ 



create a new, custom screen from a tag list. Use either one 
of these with Release 2 (V36) or later versions of the OS. 
Create a new, custom screen from an ExtNewScreen structure. 
Use this if your application must be compatible with 1 .3 (V34) 
or earlier versions of the operating system. 
Close a custom screen and free the memory it used. 
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Applications may wish to use tag items to set up a new screen instead of the NewScreen structure since tag 
items are often more convenient. For the sake of backwards compatibility, the ExtNewScreen structure is 
available. ExtNewScreen combines the NewScreen method used to define screens in older versions of the OS 
with the tag item method used in Release 2. The examples listed in the next section show how these various data 
structures can be used to set up a new screen. 



Custom Screen Functions 



All applications require a screen to work in. This can be an existing, public screen or a new, custom screen 
created by the application itself. To create a new, custom screen to work with, you call OpenScreen() or one of 
its variants. 



CREATING A NEW CUSTOM SCREEN 

There are three functions you can use to open a custom screen: OpenScreen(), OpenScreenTagsQ or 
OpenScreenTagListQ. Prior to Release 2 (V36), OpenScreen() was used to create a new screen. With V36 and 
later versions of the operating system, this call is superseded by OpenScreenTagListQ and 
OpenScreenTags() . 

struct Screen *OpenScreen( struct NewScreen *) 

struct Screen *OpenScreenTagList ( struct NewScreen *, struct Tagltem *) 

struct Screen *OpenScreenTags ( struct NewScreen *, ULONG, ULONG, ... ) 

The old OpenScreen() call relied on a fixed size data structure (NewScreen) which made little allowance for 
extensions and growth. The new calls are tag based, allowing for the addition of new features without 
modification of existing structures and applications. The "Screen Attributes" section below contains a complete 
list of all the tag options available for setting up an Intuition screen. For a general description of tag items, see the 
"Utility Library" chapter. 

A Custom Screen Example 

There are so many tag options available with screens it can be a bit overwhelming. Before discussing more 
details, it may be helpful to look at a simple example. The code below opens a new, custom screen using the 
OpenScreenTags() call. The example uses just two tag items (SA_Depth and SA_Pens) which provide the 
minimum attributes needed to make a screen That uses the new 3D look of Intuition available in Release 2. (See 
the section on "Drawlnfo and the 3D Look" below for more information.) 
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/* newlookscreen. c 

** open a screen with the "new look" . 



* * 



** SAS/C 5.10a 

** lc -bl -cfist -v -y newlookscreen 

** blink LIB:c.o newlookscreen . o TO newlookscreen LIB LIB :1c. lib LIB :amiga . lib */ 

#define INTUI_V3 6_NAMES_ONLY 
#include <exec/types . h> 
#include <intuition/intuition.h> 
#include <intuition/screens .h> 
#include <clib/exec_protos . h> 
#include <clib/dos_protos .h> 
#include <clib/intuition protos.h> 
#ifdef LATTICE 

int CXBRK(void) { return(O); } /* Disable Lattice CTRL/C handling */ 

int chkabort (void) { return (0); } /* really */ 
#endif 

struct Library *IntuitionBase; 

/* Simple routine to demonstrate opening a screen with the new look. 

** Simply supply the tag SA_Pens along with a minimal pen specification, 

** Intuition will fill in all unspecified values with defaults. 

** Since we are not supplying values, all are Intuition defaults. */ 

VOID main (int argc, char **argv) 

{ 

UWORD pens [] = ( ~0 ) ; 
struct Screen *my screen; 

IntuitionBase = OpenLibrary ( "intuition. library" , 0) ; 

if (NULL != IntuitionBase) 

{ 



if (IntuitionBase->lib_Version >= 37) 

{ 

/* The screen is opened two bitplanes deep so that the 

** new look will show-up better. */ 

if (NULL != (my_screen = OpenScreenTags (NULL, 

SA_Pens, (ULONG)pens, 
SA_Depth, 2, 
TAG_DONE) ) ) 

{ 
/* screen successfully opened */ 
Delay (30L) ; 
/* normally the program would be here */ 

CloseScreen (my screen); 
} 
} 
CloseLibrary (IntuitionBase) ; 



The example above runs only under Release 2 (V36) and later versions of the OS. To make a custom screen that 
works under both Release 2 and earlier versions of the operating system, use the original OpenScreen() 
function. 

The NewScreen structure used with OpenScreenQ has been extended with a tag list in V36 to form an 
ExtNewScreen. This is done by setting the NS_EXTENDED bit in the Type field of the NewScreen structure and 
adding a pointer to an array of tags to the end of the structure. The NS_EXTENDED bit is ignored in older 
versions of the operating system, so the tags can be transparently added to existing applications and the features 
will appear when executed in a system running V36 or greater. See the OpenScreen() Autodocs and the include 
file <intuition/screens.h> for more information on NS EXTENDED and the ExtNewScreen structure. 
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Creating A Custom Screen that Works With Older Systems 

Here's an example of how to use the old OpenScreenQ call with an ExtNewScreen structure to make a new, 
custom screen under any version of the Amiga operating system. If the version is V36 or later, additional Release 
2 features specified via tags, in this case the new 3D look of Intuition, will be incorporated in the window. 

/* screen34to37 . c - Execute me to compile me with SAS 5.10 

LC -bl -cfistO -v -y -J73, screen34to37 . c 

blink FROM LIH:c.o screen39to37 . o TO screen39to37 LIH LIB :1c. lib LIB : amiga . lib 

quit 
*/ 



#define INTUI V36 NAMES ONLY 



/* We'll use the newer Intuition names. */ 



#include <exec/types . h> 
#include <intuition/intuition.h> 
#include <intuition/gcreens . h> 
#include <clib/exec_protos . h> 
#include <clib/dos protos.h> 
#include <clib/intuition protos.h> 

#ifdef LATTICE 

int CXBRK(void) { return(O); } 

int chkabort (void) ( return (0); } 

#endif 



/* Amiga data types. */ 

/* Lots of important Intuition */ 

/* structures we will be using. */ 

/* Function prototypes */ 



/* Disable Lattice CTRL/C handling */ 
/* really */ 



struct Library * IntuitionBase; 



/* Intuition library base 



/* Simple example to show how to open a custom screen that gives the new look 

* under V3 7, yet still works with older version of the operating system. 

* Attach the tag SA_Pens and a minimal pen specification to ExtNewScreen, 

* and call the old OpenScreenO function. The tags will be ignored by 



* V39 and earlier versions Of the OS. In V36 and later the tags are 

* accepted by Intuition. 
*/ 

VOID main(int argc, char **argv) 

{ 

UWORD pens [ ] = [ ~0 } ; /* This is the minimal pen specification*/ 

struct Screen *my_screen; /* Pointer to our new, custom screen */ 

struct ExtNewScreen myscreen_setup; /* Same as NewScreen with tags attached 

*/ 

struct Tagltem myscreen_tags [2] ; /* A small tag array */ 

/* Open the library before you call any functions */ 
IntuitionBase = OpenLibrary ( "intuition. library" , 0) ; 
if (NULL != IntuitionBase) 



{ 



/* Fill in the tag list with the minimal pen specification */ 
myscreen_tags [0] . ti_Ta() =SA_Pens; 
myscreen_tags [0] . ti_Data= (ULONG) pens; 
myscreen_tags [1] . ti Tag=TAGDONE; 

/* The screen is opened two bitplanes deep so that the 
** new look will show-up better. 

*/ 
myscreen_setup . Lef tEdge=0 ; 
myscreen_setup . TopEdge=0 ; 

myscreen_setup .Width=640 ; /* Smaller values here reduce 

myscreen_setup .Height=STDSCREENHEIGHT; /* drawing area and save memory.*/ 

myscreen_setup .Depth=2 ; /* Two planes means 4 colors. */ 

myscreen_setup . DetailPen=0 ; /* Normal V34 pen colors. */ 

myscreen_setup . BlockPen=l ; 
myscreen_setup . ViewModes^HIRES.- 
myscreen^setup .Type=CUSTOMSCREEN | NS_EXTENDED; /* Extended NewScreen flag */ 
myscreen_setup . Font=NULL ; 
myscreen_setup . Def aultTitle="My Screen" ; 
myscreen_setup . Gadget s=NULL; 
myscreen_setup . CustomBitMap=NULL ; 

/* Attach the pen specification tags to the ExtNewScreen structure */ 
myscreen_setup . Extension=myscreen_tags ; 
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if (NULL != (my_screen = OpenScreen ( (struct NewScreen *)&myscreen setup))' 

{ 

/* screen successfully opened */ 

Delay (200L) ; /* normally the program would be here */ 

} 



} 



} 



CloseScreen (my screen) 



As you can see from the examples above, there are many ways to create a new, custom, screen. Further 
references to "OpenScreenTagListO" in this manual are referring to any one of -the three calls: 
OpenScreenTagList(), OpenScreenTagsQ, or OpenScreenQ used with tags in an ExtNewScreen as shown 
above. 

Return Values from OpenScreenTagListO 

OpenScreenTagListO and its variants return a pointer to a Screen structure on the successful creation of a new 
screen and NULL on failure. With V36, the call now supports extended error codes on failure. The error returns 
provide information on the type of failure, giving the application a greater chance of recovery. To get the 
extended error code, you need to use the SA ErrorCode tag; the code itself will be placed into the LONG pointed 
to by the Tagltem.ti_Data field. Here are the codes: 

OSERR_NOMONITOR 

The monitor needed to display the requested mode is not available. An example of this error would be 



opening a Productivity mode screen on a system without a VGA or multisync monitor. 

OSERR_NOCHIPS 

Newer custom chips are required for this screen mode. For instance, the ECS Denise is required for 
the productivity modes. 

OSERR_NOMEM 

Could not allocate enough memory. 

OSERR_NOCHIPMEM 

Could not allocate enough Chip memory. 

OSERR_PUBNOTUNIQUE 

Could not create public screen name already used. The system requires that public screen names be 
unique. 

OSERRJJNKNOWNMODE 

Display mode requested was not recognized. The system does not understand the value specified with 
theSA_DisplaylDtag. 

Closing the Screen 

When an application has finished using a screen, the memory that the screen occupied should be returned to the 
system by calling CloseScreen(). Normally, an application should close only those screens that it created. Under 
V34 and earlier versions of the OS, CloseScreen() returns no values. Under Release 2, CloseScreen() returns a 
boolean value, TRUE for success and FALSE for failure. CloseScreen() can fail if the screen is public and 
another task is still using the screen. 
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SCREEN ATTRIBUTES 

The sections above discuss only the basic functions and screen types that Intuition programmers need to 
understand to create a custom screen. Intuition supports an astonishing number of additional display features 
and options. In this section and the sections to follow, the finer points of screen attributes and the functions that 
control them are presented. 

Screen attributes are specified using the tag item scheme described in the "Utility Library" chapter. Therefore, the 
screen attributes are listed here by tag values. (In V34, the NewScreen structure was used to set screen 
attributes so many of the tag options listed here have a corresponding flag in NewScreen.) In general, specifying 
a tag overrides the corresponding flag or field in the NewScreen structure -if you supply one. 

SA ErrorCode 

Extended error code. Data is a pointer to a long which will contain the error code on return if 
OpenScreenTagList() returns NULL. The error codes are described above. 

SA Left, SA Top 

Initial screen position (left edge and top edge). Data is a long, signed value. Offsets are relative to the 
text overscan rectangle. 

If SALeft is not specified and a NewScreen structure is not passed in the OpenScreenTags/TagList() 
call and SA_Width is not specified or is specified as STDSCREENWIDTH, then the left edge of the 
screen will default to the left edge of the actual display clip of the screen. If the other conditions are met 
but some explicit SA_Width is specified, then the left edge defaults to zero (text overscan rectangle left 
edge). Likewise, the top edge may, independent of the left edge value, default to zero or to the top edge 
of the actual display clip. If SATop is not specified and a NewScreen structure is not passed in the 
OpenScreenTags/TagList() call and SAJHeight is not specified or specified as STDSCREENHEIGHT, 
then the top edge of the screen will default to the top edge of the actual display clip of the screen. If the 
other conditions are met but some explicit SAJHeight is specified, then the top edge defaults to zero 
(text overscan rectangle top edge). Prior to V36, left edge positioning is ignored and negative top edge 
positions are illegal. 



When opening a full sized overscan screen, SA_Left should be set to the MinX value of the display clip 
Rectangle used for the screen and SA_Top should be set to the MinY value of the display clip. This 
may be taken from the defaults, as explained above, or explicitly set by the application. See the section 
below on "Overscan and the Display Clip" and the OpenScreen() Autodoc for more details. 

If your screen is larger than your display clip, you may wish to set the SA_Left and SA_Top to values 
less than your display clip MinX and MinY in order to center a large screen on a smaller display. For an 
example of how to open a centered overscan screen, see module/screen. c in the IFF Appendix of the 
Amiga ROM Kernel Reference Manual: Devices. 

SA_Width, SA_Height 

Screen dimensions. Data is a long, unsigned value. These may be larger, smaller or the same as the 
dimensions of the display clip Rectangle. The use of STDSCREENWIDTH and STDSCREENHEIGHT 
will make the screen size equal to the display clip size. 

To calculate the width of the display clip Rectangle, subtract the MinX value from the MaxX value plus 
one. Similarly, the height of the display clip may be calculated by subtracting the MinY value from the 
MaxY value plus one. 
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SA_Depth 

Screen bitmap depth. Data is a long, unsigned value. The depth of the screen determines the number of 
available colors. See the "Graphics Primitives" for more information on hardware limitations of the 
display. Do not set the depth to a value greater than that supported by the specific display mode. This 
information is available to the application through the graphics library display database. The default is 
one bitplane. 

SADIsplaylD 

Extended display mode key for the screen. Data is a long, unsigned value. By using Release 2 
DisplaylDs and the display database, applications can open a screen in any display mode available on 
a user's system, including PAL and NTSC modes. See the discussion of the display database in the 
"Graphics Primitives" chapter and the include file <graphics/displayinfo.h> for more information. 

SA Pens 

Pen specification for the screen. Data is a pointer to a UWORD array terminated with -o, as found in the 
Drawlnfo structure. Specifying the SA Pens tag informs the system that the application is prepared to 
handle a screen rendered with the new 3D look of Intuition. See the section below on "Drawlnfo and the 
3D Look". Omitting this tag produces a screen with a flat look, but whose color usage is more backwards 
compatible. 

SA_DetailPen 

Detail pen for the screen. Data is a long, unsigned value. Used for rendering details in the screen title 
bar and menus. Use SA_Pens beginning with V36 for more control of pen specification. If SA_Pens is 
not specified, the screen will not get the new 3D look of Intuition available in Release 2. Instead this 
value will be used as the detail pen. 

SA BlockPen 

Block pen for the screen. Data is a long, unsigned value. Used for rendering block fills in the screen title 
bar and menus. Use SA_Pens beginning with V36 for more control of pen specification. If SA_Pens is 
not specified, the screen will not get the new 3D look and this value will be used as the block pen. 

SA_Title 

Default screen title. Data is a pointer to a character string. This is the title displayed when the active 
window has no screen title or when no window is active on the screen. 

SA_Colors 

Specifies initial screen palette colors. Data is a pointer to an array of ColorSpec structures, terminate by 
a ColorSpec structure with Colorlndex = -1 . Screen colors may be changed after the screen is opened 
with the graphics library functions SetRGB4() and LoadRGB4(). ColorSpec colors are right-justified, 
four bits per gun. 



SA_FullPalette 

Initialize color table to entire preferences palette (32 colors beginning with V36), rather than the subset 
from V34 and earlier, namely pens 0-3,17-19, with remaining palette as returned by GetColorMap(). 
Data is a boolean value (use TRUE to set the flag). Defaults to FALSE. 



SA_FontData 

is a pointer to a TextAttr structure (defined in <graphics/text.h> ) 
to use for the screen. Equivalent to NewScreen.Font. 



which specifies the font, size and style 
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SA_SysFont 

Alternative to SA 



Font. Selects one of the preferences system fonts. Data is a long, unsigned value, 



What you tell OpenScreen() 


Screen font 


Window.RPort font 


A. NewScreen.Font = myfont 


myfont 


myfont 


B. NewScreen.Font = NULL 


GfxBase->DefaultFont 


GfxBase->DefaultFont 


C. {SA Font, myfont) 


myfont 


myfont 


D. {SA SysFont, 0} 


GfxBase->DefaultFont 


GfxBase->DefaultFont 


E. {SA SysFont, 1} 


Font Prefs Screen text 


GfxBase->DefaultFont 



with the following values defined: 

Open screen with the user's preferred fixed width font (the default). 

1 Open screen with the user's preferred font, which may be proportional. 

The Workbench screen is opened with {SA_SysFont, 1}. Table 3-4 summarizes how the font selected at 
OpenScreen() time effects subsequent text operations in screens and windows. 

Table 3-4: Intuition Font Selection Chart 



Notes: 



A and B are the options that existed in V34 and earlier OS versions. 

C and D are tags in Release 2 equivalent to A and B respectively. 

E is a new option for V36. The Workbench screen uses this option. 

For 'myfont', any font may be used including a proportional one. This is true under all releases of the OS. GfxBase->DefaultFont is always 

monospace. (This is the "System Default Text" from Font Preferences.) Font Prefs Screen text (the "Screen Text" choice from Font 

Preferences) can be monospace or proportional. 

The screen's font may not legally be changed after a screen is opened. The menu bar, window titles, 
menu items, and the contents of a string gadget all use the screen's font. The font used for menu items 
can be overridden in the menu item's IntuiText structure. Under V36 and higher, the font used in a 
string gadget can be overridden through the StringExtend structure. The font of the menu bar and 
window titles cannot be overridden. 

The Window.RPort font shown above is the initial font that Intuition sets in your window's RastPort. It is 
legal to change that subsequent with SetFontQ. IntuiText rendered into a window (either through 
PrintlTextQ or as a gadget's GadgetText) defaults to the window's RastPort font, but can be 
overridden using its ITextFont field. Text rendered with the graphics library call TextQ uses the 
window's RastPort font. 



SA_Type 



Equivalent to the SCREENTYPE bits of the NewScreen.Type field. Data is a long, unsigned value 
which may be set to either CUSTOMSCREEN or PUBLICSCREEN (WBENCHSCREEN is reserved for 
system use). See the tags SA_BitMap, SA_Behind, SA_Quiet, SA_ShowTitle and SA_AutoScroll for the 
other attributes of the NewScreen.Type field. 



SA_BitMap 

Use a custom bitmap for this screen. Data is a pointer to a BitMap structure. This tag is equivalent to 
NewScreen.CustomBitMap and implies the CUSTOMBITMAP flag of the NewScreen.Type field. The 
application is responsible for allocating and freeing the screen's bitmap. 
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SA_Behind 

Open this screen behind all other screens in the system. Data is a boolean value (TRUE to set flag). 
This tag is equivalent to the SCREENBEHIND flag of the NewScreen.Type field. 

SA_Quiet 

Disable Intuition rendering into screen. Data is a boolean value (TRUE to set flag). This tag is 
equivalent to the SCREENQUIET flag of the NewScreen.Type field. The screen will have no visible title 
bar or gadgets, but dragging and depth arrangement still function. In order to completely prevent 
Intuition from rendering into the screen, menu operations must be disabled for each window in the 
screen using WFLG_RMBTRAP. 

SA ShowTitle 

Setting this flag places the screen's title bar in front of any backdrop windows that are opened on the 
screen. Data is a boolean value (TRUE to set flag). This tag is equivalent to the SHOWTITLE flag of the 
NewScreen.Type field. The title bar of the screen is always displayed behind any non-backdrop 
windows on that screen. This attribute can be changed after the screen is open with the ShowTitle() 
function. 

SA_AutoScroll 

Setting this flag will enable autoscroll for this screen when it is the active screen. (Currently, the 
screen may only be made active by activating a window in that screen either under user or application 
control.) Data is a boolean value (TRUE to set flag). This tag is equivalent to the AUTOSCROLL flag 
of the NewScreen.Type field. 

Autoscroll means that screens larger than the visible display will automatically scroll when the user 
moves the mouse to the edge of the screen. Without this tag, the user moves the screen either by using 
the screen drag bar, or by pressing the mouse select button anywhere within the screen while holding 
down the left Amiga key and moving the mouse. 

SA_PubName 

Presence of this tag means that the screen is to be a public screen. Data is a pointer to a string. The 
string is the name of the public screen which is used by other applications to find the screen. This tag is 
order dependent, specify before SA_PubSig and SA_PubTask. 

SA_PubSig, SA_PubTask 

Task ID (returned by FindTaskQ) and signal for notification that the last window has closed on a public 
screen. Data for SA_PubSig is a long, unsigned value. Data for SA_PubTask is a pointer to a Task 
structure. These two tags are order dependent, and must be specified after the tag SA_PubName. 

SA_Overscan 

Set to one of the OSCAN_ specifiers to use a system standard overscan display clip and screen 
dimensions (unless otherwise specified). Data is a long, unsigned value. Do not specify this tag and 
SA_DCIip. SA_Overscan is used to get one of the standard overscan dimensions, while SA_DCIip is for 
custom dimensions. If a display clip is not specified with either SA_Overscan or SA_DCIip, the display 
clip defaults to OSCAN_TEXT. See the section below on "Overscan and the Display Clip" for more 
information. 

SA_DCIip 

Custom display clip specification. Data is a pointer to a Rectangle structure that defines the screen 
display clip region. 
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Public Screen Functions 



Public screens are a new feature of Release 2 (V36). A public screen allows multiple applications to share a 
single screen thus saving memory. If your application opens a public screen, then other applications will be able 



to open their windows on your screen. In older versions of the operating system, only the Workbench screen 
could be shared so applications had to live within its limitations or use up Chip memory creating their own private, 
custom screens. 

Now the system allows any screen to be set up as a public screen so there may be many public screens in 
memory at once, not just Workbench. This permits the power user to set up different work environments that 
multiple applications can share in a way that is memory resident (each one with a display mode appropriate to a 
particular job). 

Workbench is a special case public screen because it is the initial default public screen. The default public screen 
is the screen applications will get when they ask for a public screen but don't specify a name. Under normal 
conditions, Workbench is the default public screen and is created by the system at startup time. However, keep in 
mind that the default public screen can be changed (it's not always guaranteed to be Workbench). 

Screens for the Novice. If you're not sure what kind of screen to use, then use the default 
public screen. Under Release 2, you can open a window on the default public screen without 
doing any screen set-up work. See the "Intuition Windows" chapter for more details. 

Generally, it is much easier to use an existing, public screen than to set up one of your own. Here are the basic 
functions you use to work with an existing public screen. 



Table 3-5: Public Screen Functions 

LockPubScreen() Find Workbench or any other public screen; prevent it from closing while 

a window is opened or its attributes copied. 
UnlockPubScreenQ Release the lock allowing the screen to later be closed. 

SetDefaultPubScreen() Establishes a given public screen as the default. 
GetDefaultPubScreen() Copies the name of the default screen to a user supplied buffer for use by 

the screen manager utility (the name is not needed by normal applications, 
use LockPubScreen(NULL) instead). 



PubScreen5tatus() Converts a screen to private or public status. SetPubScreenModes() 

Controls the public screen global mode bits. 

By using an existing public screen, an application is no longer responsible for setting up the display, however, it 
also loses flexibility and control. It can no longer set the palette or depth, and it cannot write directly into screen 
memory without cooperation from the owner of the public screen. (If these limitations are loo confining, the 
application can create a new screen instead.) 
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ACCESSING A PUBLIC SCREEN BY NAME 

The main calls for accessing an existing public screen are LockPubScreen() and UnlockPubScreen(). To use 
these functions you need to know the name of the public screen you want to access. If you do not know the name 
of the public screen or if you are not sure, you can lock the default public screen with LockPubScreen(NULL). 

struct Screen *LockPubScreen ( UBYTE * ) 

VOID UnlockPubScreen( UBYTE *, struct Screen *) 

These calls enable the application to determine that a public screen exists, and to ensure its continued existence 
while opening a window on it. This function also serves as an improvement over the old GetScreenDataQ 
function from V34 by returning a pointer to the Screen structure of the locked screen so that its attributes can be 
examined. 

Be sure to unlock the public screen when done with it. Note that once a window is open on the screen the 
program does not need to hold the screen lock, as the window acts as a lock on the screen. The pointer to the 
screen structure is valid as long as a lock on the screen is held by the application, or the application has a 
window open on the screen. 

Locks should not be held without reason. Holding unnecessary locks on screens may prevent the user from 
closing a public screen that has no apparent activity. Keep in mind that as long as you have a window open on a 
public screen, the window acts as a lock preventing the screen from closing. 



Shown here is a simple example of how to find the Workbench public screen using LockPubScreen() and 
UnlockPubScreenQ. 

;/* pubscreenbeep . c - Execute me to compile me with SAS 5.10 
LC -bl -cfistO -v -y -J73 pubscreenbeep . c 

blink LIB:c.o pubscreenbeep . o TO pubscreenbeep LIB LIB :1c. lib LIB;amiga . lib 
quit 
*/ 

#include <exec/types . h> 
#include <exec/libraries . h> 
#include <intuition/intuition.h> 
#include <intuition/screens .h> 

#include <clib/exec_protos . h> 
#include <clib/intuition protos.h> 

#ifdef LATTICE 

int CXBRK(void) { return ( ) ; } 

int chkabort (void) { return (0); } 
#endif 

struct Library *IntuitionBase; /* Intuition library base */ 

/* Simple example of how Lo find a public screen to work with in Release 2. */ 

VOID main (int argc, char **argv) 

{ 

struct Screen *my wbscreen ptr; /* Pointer to the Workbench screen */ 

/* Open the library before you call any functions */ 
IntuitionBase = OpenLibrary ( "intuition. library" , 0) ; 
if (NULL != IntuitionBase) 

{ 

if (IntuitionBase->lib Version>=36) 

{ 

/* OK, we have the right version of the OS so we can use 
** the new public screen functions of Release 2 (V36) */ 
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if (NULL! = (my wbscreen_ptr=LockPubScreen ( "Workbench" ) ) ) 

{ 

/* OK found the Workbench screen. */ 

/* Normally the program would be here. A window could */ 
/* be opened or the attributes of the screen copied */ 
DisplayBeep (my wbscreen ptr) ; 

UnlockPubScreen (NULL, my wbscreen ptr); 
} 
} 
else 

{ 

/* Prior to Release 2 (V36) , there were no public screens, */ 

/* just Workbench. In those older systems, windows can be */ 

/* opened on Workbench without locking or a pointer by setting */ 

/* the Type=WBENCHSCREEN in struct NewWindow. Attributes can */ 

/* be obtained by setting the Type argument to WBENCHSCREEN in */ 

/* the call to GetScreenData ( ) . */ 

} 

CloseLibrary (IntuitionBase) ; 



} 



} 



THE DEFAULT PUBLIC SCREEN AND WORKBENCH 

As mentioned earlier, Workbench is a special case public screen because it is the initial default public screen. 
There are other reasons Workbench has a special status. Normally, it's the first thing the user sees because it is 



the default user interface on all Amiga computers. Many older applications written for V34 and earlier versions of 
the OS expect to run in the Workbench screen. Also, Workbench is currently the only public screen supported by 
system Preferences and the only screen Intuition can automatically open. 

Because of its close ties with the operating system, there are some extra functions available to manipulate the 
Workbench screen. One function which controls both Workbench and other public screens is 
SetPubScreenModes(). This function controls the global public screen mode bits, SHANGHAI and 
POPPUBSCREEN. If the SHANGHAI mode bit is set, older applications which expect to open on the Workbench 
screen will open instead on the default public screen (which may or may not be the Workbench screen). The 
POPPUBSCREEN bit controls whether public screens will be popped to the front when a window is opened. 
These modes are documented in the "Intuition Windows" chapter in the section on "Windows and Screens". 



WBenchToBack() Move the Workbench screen behind all other screens. 

WBenchToFront() Move the Workbench screen in front of all other screens. 

OpenWorkBench() Open the Workbench screen. If the screen is already open, this call has 

no effect. This call will re-awaken the Workbench application if it was active when 

CloseWorkBench() was called. 
CloseWorkBench() Attempt to reclaim memory used for the Workbench screen. If successful, this call 

closes the screen and puts the Workbench application to sleep. This call fails if any 

application has windows open or locks on the Workbench screen. 



Other functions which control the Workbench screen are listed in the table below. 

Table 3-6: Workbench Public Screen Functions 
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Programs can attempt to reclaim memory used by the Workbench screen by calling CloseWorkBench(). 
Programs that have closed Workbench, should call OpenWorkBenchQ as they exit or allow the user to re- open 
the screen through a menu or gadget. 

If Workbench is closed, any of the following events can re-open it: calling OpenWorkBenchQ: opening a window 
on the Workbench (including EasyRequestsQ such as the DOS "Insert Disk" requester); calling 
LockPubScreen("Workbench"); calling LockPubScreen(NULL) when Workbench is the default public screen. 

TAKING A NEW CUSTOM SCREEN PUBLIC 

Applications that open a new screen should consider taking the screen public. If the screen's characteristics are 
not very esoteric, making the screen public is useful because it allows other applications to share the working 
context. This makes an application more powerful and more attractive to the user because it allows the user to 
add supporting applications and utilities from other vendors to make a customized and integrated work 
environment. 

To make your own custom screen into a public screen that other applications may use, you give the screen a 
public name and then register the screen with Intuition. The screen must be declared as public in the 
OpenScreenTagList() call by specifying a public name string with the SA_PubName tag. The application's task ID 
and a signal bit may also be registered when the screen is opened with the SA_PubTask and SA_PubSig tags. If 
these tags are given, the system will signal your task when the last window on the screen closes. 

When a new public screen is opened, it starts out private so the application can perform any desired initialization 
(for instance, opening a backdrop window) before the screen is made public. Use the PubScreenStatusQ 
function to make the screen public and available to other applications (or to take the screen private again, later). 
The screen may not be taken private or closed until all windows on the screen are closed and all locks on the 
screen are released. However, the screen does not need to be made private before closing it. 

CloseScreen() will fail if an attempt is made to close a public screen that still has visitor windows or locks on it. If 
the user selects close screen, but the screen will not close due to visitor windows, a requester should be 
displayed informing the user of the condition and instructing them to close any windows before closing the 
screen. 



SEARCHING THE PUBLIC SCREEN LIST 

To access an existing public screen the application may take one of three approaches. To get a lock on the 
default public screen, either LockPublicScreen(NULL) or ( WA_PubScreenName, NULL) may be used. 

If the name of the screen is known, the application may use LockPubScreen(Name) to gain a lock on the screen 
as shown in the example above (or use OpenWindowTagList() with the WA_PubScreenName tag as 
described in the "Intuition Windows" chapter). Failure to lock the screen or open the window probably indicates 
that the screen does not exist. 
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A third approach is to search the public screen list for a screen that meets the requirements of the application. 



LockPubScreenList() Lock the public screen list maintained by Intuition so that it may be quickly copied 
UnlockPubScreenList() Release the lock on the public screen list 
NextPubScreenQ Find the next screen in the public screen list . 



These requirements may be related to the name or attributes of the screen. Here are the functions to use with the 
public screen list maintained by Intuition. 

Table 3-7: Public Screen List Functions 

The main function used to access the public screen list is LockPubScreenList(). This function, intended for use 
by the public screen manager utility, locks the list to allow data from it to be quickly copied. The list is stored in an 
Exec List structure, with each node in the list being a PubScreenNode structure. See <intuition/screens.h> for 
details. 

Do not interpret the list while in a locked state, instead, copy any values required to local variables and release 
the lock. All required data must be copied, including the name of the screen which is not part of the structure. 
Pointers that reference the list or structures attached to the list are not valid after releasing the lock. Once the 
lock is released, the screen pointers in the list (psn_Screen) may be tested for equality against other screen 
pointers, but referencing any part of the screen structure from this pointer is strictly illegal. After the lock is 
released with UnlockPubScreenList(), the application may access the data in the screen structure by obtaining 
a lock on the screen using LockPubScreen() with the name of the screen. 

The application should only require accessing three fields in the PubScreenNode, these are ln_Name, 
psn_Screen and psnFlags. The name of the public screen is maintained in the ln_Name field of the Node 
(psn_Node) structure. Access to other information on the screen may be done by getting a lock on this name 
and reading the data from the Screen structure. The screen pointer (psn_Screen) may only be used for testing 
against other screen pointers, never reference the screen structure from this value. Finally, the public screen 
flags are maintained in psn_Flags. Currently, only PSNF_PRIVATE is defined for this field. PSNF_PRIVATE 
indicates that the screen is not currently public. 

Remember that all information in the public screen list is transitory, that is, it may change at any time. Do not rely 
on the values in the list. The only way to ensure the existence or mode of a screen is to lock it, either directly with 
LockPubScreen() or by opening a window on the screen. To update the copy of the list, lock it and copy the data 
again. Don't forget to release the lock when finished. 

As an alternative to dealing with the public screen list, NextPubScreenQ can he used. This call takes the name 
of a public screen as its argument and returns the name of the next screen in the public screen list. This helps an 
application move a window through the entire rotation of public screens. Repeated calls to NextPubScreen() 
could be used to get the names of all public screens one at a time. Keep in mind though that the list of public 
screens is subject to sudden change; the task that owns a public screen might close it after you obtain the name, 
but before you access the screen. 

Always use LockPubScreenQ to access screen information after scanning the public screen list. 
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Drawlnfo and the 3D Look 



In Release 2, whenever a new screen is created, Intuition also creates an auxiliary data structure called a 
Drawlnfo. The Drawlnfo structure provides information Intuition uses to support the new 3D look of Release 2 
and specifies graphical information for applications that use the screen. The information includes such items as 
aspect ratio (resolution), font, number of colors and drawing pens. 

struct Drawlnfo 

{ 

UWORD dri_Version; /* will be DRIJVERSION */ 

UWORD dri_NumPens ; /* guaranteed to be >= numDriPens */ 

UWORD *dri_Pens; /* pointer to pen array */ 

struct TextFont *dri_Font; /* screen default font _ */ 

UWORD dri_Depth; /* (initial) depth of screen bitmap */ 

struct /* from Displaylnfo database for initial display 
mode */ 

{ 

UWORD X; 

UWORD Y; 
} dri_Resolution; 

ULONG dri_Flags; /* defined below */ 

ULONG dri_Reserved [7] ; /* avoid recompilation ;~) */ 

}; 

Before an application uses fields in the Drawlnfo structure, it should check the version of the structure to ensure 
that all fields are available. If the field dri_Version is greater than or equal to the constant DRI_VERSION that 
the application was compiled with, it can be assured that all fields in Drawlnfo that it knows about are being 
supported by Intuition. 

THE PEN SPECIFICATION IN DRAWINFO 

The drawing pen specification in Drawlnfo.dri_Pens allows applications to use appropriate colors for graphic 
operations such as drawing text, shading 3D objects and filling items selected by the user. 

Intuition has two default sets of pens, one for multi-bitplane screens and one for single bitplane screens. In 
addition, there is a special compatibility mode for screens that do not specify the SA Pens tag. 

New 3D Look 

The is the full 3D look as found by default on the Workbench screen in Release 2. Objects are drawn 
so that light appears to come from the upper left of the screen with shadows cast to the lower right 
giving them a three-dimensional look. 

Monochrome New Look 

It is impossible to produce the full 3D look in a single bitplane (two color) screen. Intuition provides a 
fallback pen specification that is used in monochrome screens with no loss of information. 

Compatible New Look 

Custom screens that do not provide the SA Pens tag are assumed to have no knowledge of the pen 
array. They are rendered in a special version of the monochrome new look, which uses the screen's 
DetailPen and BlockPen to get its colors. This is provided for compatibility with V34 and older versions 
of the operating system. 

It is very easy for an application to use the default pen specification. Simply specify an empty pen specification (in 
C, {~0}), and Intuition will fill in all of the values with defaults appropriate for the screen. This technique is 
demonstrated in the first two examples listed earlier in this chapter. 
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For certain applications, a custom pen specification is required. A custom pen specification is set up when the 
screen is opened by using the SA Pens tag and a pointer to a pen array. Currently, Intuition uses nine pens to 
support the 3D look. The application can specify all of these, or only a few pens and Intuition will fill in the rest. 
Intuition will only fill in pens that are past the end of those specified by the application, there is no facility for using 
default values for "leading" pens (those at the beginning of the array) without using the defaults for the rest of the 
pens. 

Using the pen specification of an existing public screen is a bit more involved. First, the application must get a 
pointer to the screen structure of the public screen using the LockPubScreenQ call. A copy of the screen's 
Drawlnfo structure may then be obtained by calling GetScreenDrawlnfoQ. The Drawlnfo structure contains a 
copy of the pen specification for the screen that can be used in the OpenScreenTagList() call with the SA_Pens 
tag. The pen array is copied to the data structures of the new screen (it is not kept as a pointer to the information 
passed), so the application may immediately call FreeScreenDrawlnfo() and UnlockPubScreen() after the new 
screen is open. 

/* publicscreen.c 

** open a screen with the pens from a public screen. 

** SAS/C 5.10a 

** lc -bl -cfist -v -y publicscreen 

** blink FROM LIBrc.o publicscreen . o TO publicscreen LIB LIB :1c. lib LIBiami a. lib 

*/ 

#define INTUI_V3 6_NAMES_ONLY 

#include <exec/types . h> 
#include <intuition/intuition.h> 
#include <intuition/screens . h> 

#include <clib/exec_protos . h> 
#include <clib/dos_protos . h> 
#include <clib/intuition protos.h> 

#ifdef LATTICE 

int CXBRK(void) { return(O); } /* Disable Lattice CTRL/C handling */ 

int chkabort (void) { return(O) ; } /* really */ 
#endif 

VOID usePubScreenPens (void) ; 

struct Library * IntuitionBase; 

/* main() : open libraries, clean up when done. */ 
VOID main (int argc, char **argv) 

{ 

IntuitionBase = OpenLibrary ( "intuition. library" , 0) ; 
if ( IntuitionBase != NULL ) 

{ 

/* Check the version number; Release 2 is */ 
/* required for public screen functions */ 
if (IntuitionBase->lib_Version >= 37) 

{ 

usePubScreenPens ; 

} 

CloseLibrary (IntuitionBase) ; 

} 
} 

/* Open a screen that uses the pens of an existing public screen 
** (the Workbench screen in this case) . 

*/ 

VOID usePubScreenPens (void) 

{ 

struct Screen *my_screen; 
struct Tagltem screen_tags [2] ; 
UBYTE *pubScreenName = "Workbench"; 

struct Screen *pub_screen = NULL; 
struct Drawlnfo * screen drawinfo = NULL; 
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/* Get a lock on the Workbench screen */ 
pub_screen = LockPubScreen (pubScreenName) ; 
if ( pub_screen != NULL ) 

{ 

/* get the Drawlnfo structure from the locked screen */ 
screen_drawinfo = GetScreenDrawInfo (pub_screen) ; 
if ( screen_drawinf o != NULL) 

{ 

/* the pens are copied in the OpenScreenTagList ( ) call , 

so we can simply use a pointer to the pens in the tag list. 



This works better if the depth and colors of the new screen 
matches that of the public screen. Here we are forcing the 
workbench screen pens on a monochrome screen (which may not 
be a good idea) . You could add the tag: 
(SA Depth, screen drawinf o- >dri Depth) 



* * 

* * 

* * 

* * 

* * 

* * 

* * 

*/ 

screen_tags [0] .ti_Tag = SA_Pens; 

screen_tags [0] .ti_Data = (ULONG) (screen_drawinfo->dri_Pens) ; 

screen_tags [0) . ti_Tag = TAG_END; 

screen tags [O] .ti Data = NULL; 

my_screen = OpenScreenTagList (NULL, screen_tags) ; 
if (my screen != NULL) 

{ 

/* We no longer need to hold the lock on the public screen 

** or a copy of its Drawlnfo structure as we now have our 

** own screen. Release the screen. 

*/ 

FreeScreenDrawInf o (pub screen, screen_drawinfo) ; 
screendrawinfo = NULL; 

UnlockPubScreen (pubScreenName, pub_screen) ; 
pub_screen = NULL; 

DelayOO) ; /* should be rest of program */ 

CloseScreen (my screen); 
} 
} 
} 

/* These are freed in the main loop if OpenScreenTagList ( ) does 
** not fail. If something goes wrong, free them here. 

*/ 

if ( screen_drawinf o != NULL ) 

FreeScreenDrawInf o (pubscreen, screen_drawinf o) ; 
if ( pub_screen!= NULL ) 

UnlockPubScreen (pubScreenName, pub screen) ; 
} 

Beginning with V36, the pen specification for the Workbench screen happens to match the Intuition default 
specification, however, this is not required and may change in the future. To create a screen that uses the pens 
defined in the Workbench screen, the application must get a copy of the pen array from the Workbench screen 
and use this copy with the SA_Pens tag as described above. 

Here is a list of the pens defined under V36 that support the 3D look along with their uses. To read the value of a 
particular pen, use UWORD penvalue = myDrawlnfo->dri_Pens[PENNAME], where myDrawlnfo is a pointer 
to a Drawlnfo structure and PENNAME is taken from the list below: 

DETAILPEN 

Pen compatible with V34. Used to render text in the screen's title bar. 

BLOCKPEN 

Pen compatible with V34. Used to fill the screen's title bar. 

TEXTPEN 

Pen for regular text on BACKGROUNDPEN. 
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SHINEPEN 

Pen for the bright edge on 3D objects. 

SHADOWPEN 

Pen for the dark edge on 3D objects. 

FILLPEN 

Pen for filling the active window borders and selected gadgets. 

FILLTEXTPEN 

Pen for text rendered over FILLPEN. 

BACKGROUNDPEN 

Pen for the background color. Currently must be zero. 

HIGHLIGHTTEXTPEN 

Pen for "special color" or highlighted text on BACKGROUNDPEN. 

THE FONT SPECIFICATION IN DRAWINFO 

Font information for a screen comes from a number of different places. 

SA_Font 

The application may specify the font to be used in a screen by providing the SA_Font tag with a 
TextAttr structure. In this case, the font will be used by the screen and will be the default font for the 
RastPort of any window opening in the screen. 

SA_SysFont, 

If the application requests the user's preferred monospace font, it is taken from GfxBase- 
>DefaultFont. Any window's RastPorts are also initialized to use this same font. 

SA_SysFont,1 

The screen font selected by the user from the Preferences font editor may be used for the screen by 
using the SA_SysFont tag. This font, the "preferred screen font", may be proportional. For compatibility 
reasons, if this font is specified for the screen, the window's RastPort will be initialized to 
GfxBase->DefaultFont (a non-proportional font). 

To access information on an open screen's font, the application may reference Screen. Font or 
Drawlnfo.dri_Font. These fonts are identical, the Drawlnfo structure simply provides an alternate method of 
accessing the information. Note that Screen.Font is a pointer to a TextAttr structure and that 
Drawlnfo.dri_Font is a pointer to a TextFont structure. The application may use whichever font is best suited to 
its requirements. 

It is illegal to change the screen's font after the screen is opened. This means that the font specified in the 
Screen and Drawlnfo structures is guaranteed to remain open as long is the screen is open. 

The menu bar, window titles, menu items, and the contents of a string gadget all use the screen's font. The 
font used for menu items can be overidden in the menu item's IntuiText structure. Under V36 and higher, 
the font used in a string gadget can be overidden through the StringExtend structure. The font of the 
menu bar and window titles cannot be overridden. 

For more information on screen fonts, see the description of the SA_Font and SA_SysFont tags in the 
"Screen Attributes" section above. 
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CLONING A PUBLIC SCREEN (WORKBENCH) 

User preferences for screen attributes are generally reflected in the Workbench screen or in the default public 
screen. In some cases it may be useful to create a new screen with the same attributes. 

Under V34, information on a screen was available through the GetScreenData() call. Due to extensions in V36 
screen and graphics capabilities, this call is no longer sufficient to completely describe the display. Applications 
should now use a variety of calls; the specific call depends on the information required. 

LockPubScreen() returns a pointer to the Screen structure of a specific screen. GetScreenDrawlnfo() returns 
rendering information on the screen, such as the pen array and font used. QueryOverscan() returns the 
overscan information of a specific display mode (for more information, see the section on "Overscan and the 
Display Clip"). 

The example below shows how to use GetScreenDrawlnfo() to examine the attributes of the Workbench screen 
so that a new screen with the same attributes can be created. 

struct Drawlnf o *GetScreenDrawInf o ( struct Screen * ) 

The attributes required to clone an existing screen are its width, height, depth, pens and mode. The pens and 
screen depth are available through the Drawlnfo structure. The width and height may be obtained from the 
Screen structure. (The width and height may be larger than the overscan area if the screen is scrollable, and 
autoscroll may always be enabled as it does not effect displays smaller than or equal to the overscan area.) 

The screen's display mode can be obtained using the graphics library call GetVPModelD(). This call returns the 
display ID of an existing screen which can then be used as the data for the SA_DisplaylD tag in 
OpenScreenTagListQ. Note that the example assumes the screen should be open to the user's text overscan 
preference. If an exact copy of the display clip of the existing screen is required, use the VideoControl() 
command of the graphics library to access the ViewPortExtra structure. 

The colors of the screen may be copied using the graphics library calls GetRGB4(), SetRGB4(), SetRGB4CM() 
and LoadRGB4(). The example code does not copy the colors. 

The example copies the font from the cloned screen. A reasonable alternative would be to use the user's 
preference font, which may be accessed through the SA_SysFont tag. 

/* clonescreen.c 

** clone an existing public screen. 

* * 

** SAS/C 5.10a 

** lc -bl -cfist -v -y clonescreen 

** blink FROM LIBrc.o clonescreen . o TO clonescreen LIB LIB :1c. lib LIB :amiga. lib 

*/ 

#define INTUI_V36_ NAMES_ONLY 

#include <exec/types . h> 
#include <exec/memory . h> 
#include <intuition/intuition.h> 
#include <intuition/screens . h> 

#include <clib/exec_protos . h> 
#include <clib/dos_protos . h> 
#include <clib/graphics_protos . h> 
#include <clib/intuition protos.h> 

#include <string.h> 
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#ifdef LATTICE 

int CXHRK(void) ( return(O); } /* Disable Lattice CTRL/C handling */ 

int chkabort (void) ( return(O); } /* really */ 

#endif 



VOID cloneScreen ( UBYTE * ) ; 

struct Library *IntuitionBase; struct Gf xBase *Gf xBase; 

/* 

** Open all libraries for the cloneScreen ( ) subroutine. 

*/ 

VOID main(int argc, char **argv) 

{ 

UBYTE *pub_screen name = "Workbench"; 

IntuitionBase = OpenLibrary ( "intuition. library" , 0) ; 
if (IntuitionBase != NULL) 

{ 

/* Require version 37 of Intuition. */ 
if (IntuitionBase->lib Version >= 37) 

{ 

/* Note the two methods of getting the library version 

** that you really want. 

*/ 

GfxBase = (struct GfxBase *) OpenLibrary ( "graphics . library" , 37) ; 

if (GfxBase != NULL) 

{ 

cloneScreen (pub screen name) ; 

CloseLibrary ( (struct Library *)GfxBase); 
} 
} 
CloseLibrary (IntuitionBase) ; 

} 
} 

/* Clone a public screen whose name is passed to the routine. 

** Width, Height, Depth, Pens, Font and DisplaylD attributes are 

** all copied from the screen. 

** Overscan is assumed to be OSCAN_TEXT, as there is no easy way to 

** find the overscan type of an existing screen. 

** AutoScroll is turned on, as it does not hurt. Screens that are 

** smaller than the display clip will not scroll. 

*/ 

VOID cloneScreen (UBYTE *pub screen name) 

{ 

struct Screen *my_screen; 

ULONG screen_modeID; 

UBYTE *pub_scr_font_name; 

UBYTE *font_name; 

ULONG f ont_name_s i z e ; 

struct TextAttr pub_screen_f ont ; 

struct TextFont *opened_f ont ; 

struct Screen *pub_screen = NULL; 
struct Drawlnfo *screen_drawinf o = NULL; 

/* name is a (UBYTE *) pointer to the name of the public screen to clone */ 
pub_screen = LockPubScreen (pub_screen_name) ; 
if (pub_screen != NULL) 

{ 

/* Get the Drawlnfo structure from the locked screen 

** This returns pen, depth and font info. 

*/ 

screen_drawinfo = GetScreenDrawInfo (pubscreen) ; 

if (screen_drawinfo != NULL) 

{ 

screen_modeID = GetVPModelD (& (pub_screen->ViewPort) ) ; 
if ( screen_modeID != INVALID_ID ) 

{ 

/* Get a copy of the font 

** The name of the font must be copied as the public screen may 

** go away at any time after we unlock it. 
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** Allocate enough memory to copy the font name, create a 
** TextAttr that matches the font, and open the font. 

*/ 

pub_scr_f ont_name = screen_drawinf o->dri_Font->tf_Message . mn_Node . ln_Name; 
f ont_name_size = 1 + strlen (pub_scr_f ont_name) ; 
font_name = AllocMem (f ont_name_size, MEMF_CLEAR) ; 
if (font_name != NULL) 

{ 

strcpy (font_name, pub_scr_font_name) ; 

pub_screen_f ont . taName - font_name; 

pub_screen_f ont . ta_YSize - screendrawinf o- >dri_Font- >tf_YSize ; 

pub_screen_f ont . ta_Style = screen_drawinf o- >dri_Font- >tf_Style ; 

pub_screen_f ont . ta_Flags = screen_drawinfo->dri_Font->tf Flags; 

opened_font = OpenFont (&pub_screen_font) ; 
if (opened_font != NULL) 



{ 



Pens) 



/* screen_modeID may now be used in a call to 

** OpenScreenTagList ( ) with the tag SA_DisplayID. 

*/ 

my_screen = OpenScreenTags (NULL, 

SA_Width, pub_screen->Width, 

SA_Height, pub_screen- >Height , 

SA_Depth, screen_drawinf o- >dri_Depth, 

SA_Overscan, OSCAN_TEXT, 

SA_AutoScroll, TRUE, 

SA_Pens, (ULONG) (screen_drawinf o- >dri 

SA_Font , (ULONG) &pub_screen_f ont , 
SA_DisplayID, screen_modeID, 
SA_Title, "Cloned Screen", 
TAG_END) ; 
if (my screen != NULL) 

{ 

/* Free the drawinfo and public screen as we don,t 
** need them any more. We now have our own screen. 

*/ 

FreeScreenDrawInf o (pubscreen, screen_drawinf o) ; 
screendrawinfo = NULL; 

UnlockPubScreen (pub_screen_name,pub_screen) ; 
pub_screen = NULL; 

Delay (300) ; /* should be rest of program */ 

CloseScreen (my screen); 

} 

CloseFont (opened font); 

} 

FreeMem(font name, font name size); 



} 

/* These are freed in the main loop if OpenScreenTagList ( ) does 

** not fail. If something goes wrong, free them here. 

*/ 

if (screen_drawinf o l- NULL ) 

FreeScreenDrawInf o (pubscreen, screen_drawinfo) ; 

if (pubscreen != NULL ) 

UnlockPubScreen (pub screen name, pub screen); 

Overscan and the Display Clip 

Screens may be larger or smaller than the defined display area (overscan rectangle or display clip). When a 
screen is smaller than the display area, the display clip acts as a "container" for the screen. The screen may be 
moved anywhere within the display clip. When a screen is larger than the display area, the display clip acts as a 



"window" into the screen. The screen may be moved so that different parts are visible. Each dimension of the 
screen is independent and may be larger than, the same as, or smaller than the dimensions of the display clip. 
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The system is very flexible in its specification of screen size. Unless an application fixes its screen size with hard 
coded values, it should be prepared to handle the possibility that the user has changed the default overscan 
presets or the default monitor (NTSC/PAL). 

Use the constants STDSCREENHEIGHT and STDSCREENWIDTH with the SA_Width and SAJHeight tags to 
open a screen the same size as the display clip. These constants will work with any of the preset overscan 
values set with SA Overscan, and with custom overscan values set with SA_DCIip. 

PRESET OVERSCAN VALUES 

Four preset overscan dimensions are provided. Applications that support overscan should use these preset 
values where possible since they will be tailored to each individual system. Avoid using custom values that 
happen to look good on a specific system. However, be aware that the size and positioning of overscan screens 
can be different on every system depending on how the user has set Overscan Preferences. These preset values 
are also dependent on the underlying display mode so keep in mind that both offset and size parameters will 
change under different screen modes. Overscan presets can be used, among other things, with the 
SA_Overscan tag to set the size of the screen's display clip or passed as an argument to QueryOverscan() to 
find their current overscan settings. 

OSCAN_TEXT 

This overscan region is based on user preference settings and indicates a display that is completely within 
the visible bounds of the monitor. The View origin is set to the upper left corner of the text overscan 
rectangle which is the highest leftmost point known to be visible on the physical display. This position is 
set by the user through the Overscan Preferences editor. All screen positions and display clips are relative 
to this origin. 

OSCAN_STANDARD 

The edges of OSCAN_STANDARD display are also based on user preferences and are set to be just 
outside the visible bounds of the monitor. OSCAN_STANDARD provides the smallest possible display that 
will fill the entire screen with no border around it. Parts of the display created with OSCAN_STANDARD 
may not be visible to the user. 

OSCAN_MAX 

Create the largest display fully supported by Intuition and the graphics library. This is the largest size for 
which all enclosed sizes and positions are legal. Parts of the display created with OSCAN_MAX may not be 
visible to the user. 

OSCAN_VIDEO 

Create the largest display, restricted by the hardware. This is the only legal size and position that is 
possibly (but not necessarily) larger than OSCAN_MAX. You must use the exact size and position 
specified. OSCAN_VIDEO does not support variable left edge, top edge positioning. Parts of the display 
created with OSCAN_VIDEO may not be visible to the user. 

If custom clipping is required, a display clip may be explicitly specified using the SA_DCIip tag and a Rectangle 
structure specification. This custom rectangle must fit within the OSCAN_MAX rectangle, offset included. It is not 
permitted to specify custom rectangles whose values are in between OSCAN_MAX and OSCAN_VIDEO, nor is it 
permitted to specify rectangles larger than OSCAN_VIDEO. For an example of how to open a centered overscan 
screen based on user preferences, see the module/screen. c listing in the IFF Appendix of the Amiga ROM Kernel 
Reference Manual: Devices. 
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Use the Graphics library call VideoControl() to find the true display clip of a screen. See the Graphics Autodocs 
and the chapter "Graphics Primitives" for more information on VideoControl(). The ViewPortExtra structure 



contains the display clip information. 

If any dimension of a screen is not equal to the equivalent display clip dimension, then the screen may be 
scrolled. If the screen's dimensions are smaller than the display clip, then the screen may be positioned within the 
display clip. If the screen is larger than the display clip, then it may be positioned such that any part of the screen 
is visible. 

AutoScroll may be activated by setting the tag SA_AutoScroll. Screens will only scroll when they are the active 
screen. Activate a window in the screen to make the screen active. 

About the Default Display Clip. The default display clip for a screen is the entire screen, that 
is, the rectangle starting from the upper left corner of the screen and ending at the lower right 
corner of the screen. This display clip is only used if the application does not specify 
SA_Overscan or SA_DCIip. When using this default display clip the screen will not scroll as 
the screen exactly fits into the clipping region. 

When opening a window in an overscanned screen, it is often useful to open it relative to the visible part of the 
screen rather than relative to the entire screen. Use QueryOverscan() to find the overscan region and where the 
screen is positioned relative to it. 

LONG QueryOverscan (ULONG displaylD, struct Rectangle *rect, WORD overscanType ) 

This example was taken from the chapter "Intuition Windows" in the section "Visible Display Sized Window 
Example". The complete example is reproduced there. 

/* this technique returns the text overscan rectangle of the screen that we 

** are opening on. If you really need the actual value set into the display 

** clip of the screen, use the VideoControl ( ) command of the graphics library 

** to return a copy of the ViewPortExtra structure. See the Graphics 

** library chapter and Autodocs for more details. 

** GetVPModelD () is a graphics call... 
*/ 

screen_modeID = GetVPModelD (& (pub_screen->ViewPort) )) ) 
if (screen modelD != INVALID ID) 

{ 

if ( QueryOverscan (screen modelD, irect, OSCAN TEXT) ) 



{ 



} 



/* if this screen's origin is up or to the left of the */ 
/* view origin then move the window down and to the right */ 
left = max(0, -pub_screen->Lef tEdge) ; 
top = max(0, -pub screen- >TopEdge ) ; 

/* get width and height from size of display clip */ 
width = rect.MaxX - rect.MinX + 1; 
height = rect.MaxY - rect.MinY + 1; 

/* adjust height for pulled-down screen (only show visible part) */ 
if (pub_screen->TopEdge > 0) 
height -= pub screen- >TopEdge; 

/* ensure that window fits on screen */ 
height = min(height, pub_screen->Height) ; 
width = min(width, pub screen- >Width) ; 

/* make sure window is at least minimum size */ 
width = max (width, MIN_WINDOW_WIDTH) ; 
height = max (height, MIN_WINDOW HEIGHT); 
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Intuition Screens and the Graphics Library 



As previously mentioned, an Intuition screen is related to a number of underlying graphics library structures. 

Table 3-8: Graphics Data Structures Used with Screens 

Structure Name Description Defined in Include File 

View Root structure of the graphics display system <graphics/view.h> 

ViewPort The graphics structure that corresponds to a screen <graphics/view.h> 

BitMap Contains size and pointers to the screen's bit planes <graphics/gfx.h> 

ColorMap Contains size and pointer to the screen's color table <graphics/view.h> 

RastPort Holds drawing, pen and font settings and the BitMap <graphics/rastport.h> 

address 

These data structures are unified in Intuition's Screen structure (which also incorporates higher level Intuition 
constructs such as menus and windows). Here's a brief explanation of the graphics library structures used with 
Intuition. 

View 

The View is the graphics structure that corresponds to the whole display, including all visible screens. 
The system has just one View; it's what you see on the monitor. The address of the View may be 
obtained from any screen by using ViewAddress(). 

ViewPort 

The ViewPort is the underlying graphics structure corresponding to a screen. Every screen has one 
ViewPort. To get the address of the ViewPort from the Screen structure, use (&my screen->ViewPort). 
From the ViewPort an application may obtain pointers to all the screen's bitplanes and to its color table. 

BitMap 

The BitMap structure contains pointers to all the bit planes (up to 8) and their sizes. For future 
compatibility, use (my screen->RastPort. BitMap) to get the address of the BitMap from the screen 
rather than (&my screen->BitMap). 

The BitMap.BytesPerRow field specifies the number of bytes that have been allocated for each raster 
line. This may be larger than the screen width depending on display alignment restrictions. Alignment 
restrictions may change. Always use this variable, not a hard-coded value. 

ColorMap 

The ColorMap contains a pointer to the color table, an array of 32 WORDs for the hardware color 
registers. Use SetRGB4(), GetRGB4(), SetRGB4CM() and LoadRGB4() from the graphics library to 
access the color table. Do not read or write it directly. 

RastPort 

A RastPort controls the graphics rendering to any display area (not just screens). Screens have a 
RastPort to allow direct rendering into the screen. Applications may find the RastPort address of a 
screen with (&my screen->RastPort). This generally is not useful since applications normally render into 
windows. 
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CHANGING SCREEN COLORS 

Screen colors are set at the time the screen is opened with the SA_Colors tag. If the colors need to be changed 
after the screen is opened, the graphics library function, LoadRGB4() should be used. To change a single entry 
in the color table, use SetRGB4() and SetRGB4CM(). See the "Graphics Primitives" chapter for more information 
on these functions. 

DIRECT SCREEN ACCESS 

Sometimes an application may want direct access to the custom screen's bitmap to use with low-level graphics 
library calls. This may be useful if the application needs to do custom manipulation of the display but also needs 
Intuition functionality. For instance, an application may want to use the graphics library primitives to perform 
double buffering then, when detecting user input, switch to Intuition control of the screen so that windows, 



gadgets and menus may be used to process the user input. If an application chooses to combine these 
techniques, it must take special care to avoid conflicts with Intuition rendered graphics. An example of how to do 
this is listed in the next section, "Advanced Screen Programming". 

Application programs that open custom screens may use the screen's display memory in any way they choose. 
However, this memory is also used by Intuition for windows and other high level display components on the 
screen. Writing directly to the screen memory, whether through direct access or through graphics library calls that 
access the screen's RastPort, is not compatible with many Intuition constructs such as windows and menus. 

Techniques such as this require great care and understanding of the Amiga. If possible, the application should 
avoid these techniques and only use standard Intuition display and input processing. Directly accessing the 
screen's bitmap, while possible, is not recommended. A better way to access the screen display is through 
windows. Windows provide access to the screen through layers which perform clipping and arbitration between 
multiple drawing areas. 

Alternatives to writing directly to a screen, such as using a backdrop window, greatly limit the number of cases 
where an application must access screen memory. The ShowTitleQ function allows the screen's title bar layer to 
be positioned in front of or behind any backdrop windows that are opened on the screen. Hence, a backdrop 
window may be created that uses the entire visible area of the monitor. Application programs that use existing 
public screens do not have the same freedom to access the screen's display memory as they do with custom 
screens. In general, public screens must be shared Through the use of windows and menus rather than directly 
accessing the screen's display memory. 

Use Direct Access Only On Screens You Own. An application may not steal the bitmap of 
a screen that it does not own. Stealing the Workbench screen's bitmap, or that of any other 
public screen, is strictly illegal. Accessing the underlying graphics structures of a screen may 
only be done on custom screens opened by the application itself. 

Do Not Perform Layers Operations Directly. While layers are not part of the graphics 
library, it is appropriate to mention them here. Certain types of layers operations are not 
allowed with Intuition. You may not, for example, call SizeLayerQ on a window (use 
SizeWindow() instead). To access layers library features with screens, use Intuition windows! 

A custom screen may be created to allow for modification of the screen's Copper list. The Copper is the display 
synchronized co-processor that handles the actual video display by directly affecting the hardware registers. See 
the Amiga Hardware Reference Manual or the graphics library chapters for more information on programming the 
Copper. 
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MakeScreen() Update a single screen's copper list 

RethinkDisplay() Merge copper lists from all screens to form a View 

RemakeDisplayO Update all screen copper lists then merge them to form a View 



SCREEN FUNCTIONS THAT INTEGRATE INTUITION AND GRAPHICS 

These functions, normally used only by the system, integrate high-level Intuition structures with the lower- level 
constructs used by the graphics library to create the display. 

Table 3-9: Screen Functions That Integrate Intuition and Graphics 

Advanced Intuition programmers may use these functions to achieve special screen effects such as double- 
buffering or dual-playfield Intuition screens. For examples of these see the next section. 

MakeScreen() updates, but does not install, a screen's Copper list. This function is the Intuition equivalent of the 
low-level MakeVPort() graphics library function. MakeScreen() performs the MakeVPortQ call, synchronized 
with Intuition's own use of the screen's ViewPort. Call RethinkDisplayO after MakeScreenQ to allow the new 
Copper list for the screen to take effect. The MakeScreenQ function takes one argument, a pointer to the Screen 
that contains the Copper list to be updated. 



RethinkDisplay() combines all the screen's copper lists into a single view. This procedure performs The Intuition 
global display reconstruction, which includes massaging some of Intuition's internal state data, rethinking all of 
the Intuition screen Viewports and their relationship to one another, and, finally, reconstructing the entire display 
by merging the new screens into the graphics View structure. Custom screens that handle their own Copper 
instructions, use this call to install the Copper list previously updated with MakeScreenQ. RethinkDisplay() calls 
lower-level graphics primitives MrgCopQ and LoadView() to install the Copper list. This function rakes no 
arguments. 

RemakeDisplayQ remakes the entire Intuition display. It is equivalent to calling MakeScreenQ for 
each screen in the system, then calling RethinkDisplayQ. This routine performs a MakeVPort() 
(graphics primitive) on every Intuition screen and then calls RethinkDisplay() to recreate the View. 
It takes no arguments. 

Both RemakeDisplay() and RethinkDisplayQ take several milliseconds to run and lock out all other tasks while 
they run. This can seriously degrade system performance, so do not use these routines lightly. 

LIMITATIONS OF THE GRAPHICS SUBSYSTEM 

If each of the visible screens does not have the same physical attributes, it may not be possible to display the 
data in its proper screen mode. Screen coercion is the technique that allows multiple screens with differing 
physical attributes to be displayed simultaneously. When a coerced screen is visible, its aspect ratio and colors 
may appear significantly changed. This is normal and the screen will be displayed correctly when it is the 
frontmost screen. 

Hardware restrictions prevent certain types of displays. For instance, screens always use the full width of the 
display, regardless of the width of the overscan rectangle. This prevents any changes in display mode within a 
video line. Other modes, such as the VGA modes, require specific revisions of the custom chips and may not be 
available on all machines. See the "Graphics Primitives" chapter and the Amiga Hardware Reference Manual for 
more information on Amiga display organization and limitations. 
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Advanced Screen Programming 

This section discusses how to perform double-buffering of Intuition screens, how to create a dual-playfield 
Intuition screen and other advanced topics. 

DOUBLE BUFFERING 

Double buffering of an Intuition screen involves the swapping of bitmaps of the screen, then updating the copper 
list to install the changes. The trick is that after installing the bitmaps to the screen the display is not updated to 
access these new bitmaps until the program explicitly updates the copper list. Any rendering performed before 
the copper list is updated will be rendered into the off-display bitmaps, appearing on the screen in completed 
form when the copper list is updated. 

First, install the alternate bitmaps into the screen. 

/* switch the bitmap so that we are drawing into the correct place */ 
screen- >RastPort .BitMap = myBitMaps [toggleFrame] ; 

screen- >ViewPort .RasInfo->BitMap = myHitMaps [toggleFrame] ; 

Rendering may then take place into the off screen bitmaps by drawing into screen->RastPort. 

The copper list of the screen is updated by calling MakeScreenQ. This call refreshes the copper list, but does not 
install it into the system. Call RethinkDisplayO to install the new copper list so that the data is visible. 

/* update the physical display to match the newly drawn bitmap. */ 
MakeScreen (screen) ; /* Tell intuition to do its stuff. */ 
RethinkDisplayO; /* Intuition compatible MrgCop s LoadView */ 



/* it also does a WaitTOFO . */ 

Note that it is possible for the user to force the updating of the screen's copper list by dragging or depth- 
arranging the screen. This may cause information to be displayed before it is complete. 

A complete example of double buffering a screen follows. 

/* doublebuf f er . c 

** show the use of a double-buffered screen. 

* * 

** SAS/C 5.10a 

** lc -bl -cfist -v -y doublebuffer 

** blink FROM LIBic.o doublebuf fer . o TO doublebuffer LIB LIB :1c. lib LIB : amiga . lib 

*/ 

#define INTUI_V3 6_NAMES_ONLY 
#include <exec/types . h> 
#include <exec/memory . h> 
#include <intuition/intuition.h> 
#include <intuition/screens . h> 

#include <clib/exec_protos . h> 
#include <clib/graphics_protos . h> 
#include <clib/intuition protos.h> 

#ifdef LATTICE 

int CXBRK(void) return(O); } /* Disable Lattice CTRL/C handling */ 

int chkabort (void) ( return(O) ; ) /* really */ 
#endif 
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/* characteristics of the screen */ 
#define SCR_WIDTH (320) 
#define SCR_HEIGHT (200) 
#define SCR DEPTH (2) 

/* Prototypes for our functions */ 

VOID runDBuff (struct Screen *, struct BitMap ** ) ; 
struct BitMap **setupHitMaps ( LONG, LONG, LONG ); 
VOID freeBitMaps (struct BitMap **,LONG, LONG, LONG ) ; 
LONG setupPlanes (struct BitMap *, LONG, LONG, LONG ) ; 
VOID freePlanes (struct BitMap *, LONG, LONG, LONG ) ; 

struct Library * IntuitionBase = NULL; 
struct Library *Gf xBase = NULL; 

/* 

** Main routine. Setup for using the double buffered screen. 

** Clean up all resources when done or on any error. 

*/ 

VOID main (int argc, char **argv) 

{ 

struct BitMap **myBitMaps ; 
struct Screen 'screen; 
struct NewScreen myNewScreen; 

IntuitionBase = OpenLibrary ( "intuition. library" , 33L) ; 
if ( IntuitionBase != NULL ) 

{ 

GfxBase = OpenLibrary ( "graphics . library" , 33L) ; 
if ( GfxBase != NULL ) 

{ 

myBitMaps = setupBitMaps (SCR_DEPTH, SCR_WIDTH, SCR_HEIGHT) 
if ( myBitMaps != NUL.L ) 

{ 

/* Open a simple Ouiet screen that is using the first 
** of the two bitmaps. 



} 



*/ 

myNewScreen.Lef tEdge=0 ; 

myNewScreen. TopEdge=0 ; 

myNewScreen . Width=SCR_WIDTH ; 

myNewScreen. Height=SCR_HEIGHT; 

myNewScreen . Depth=SCR_DEPTH ; 

myNewScreen. DetailPen=0 ; 

myNewScreen. BlockPen=l ; 

myNewScreen . ViewModes=HIRES ; 

myNewScreen. Type=CUSTOMSCREEN | CUSTOMBITMAP | SCREENQUIET; 

myNewScreen. Font=NULL; 

myNewScreen. DefaultTitle=NULL; 

myNewScreen . Gadget s=NULL ; 

myNewScreen. CustomBitMap=myBitMaps [0) ; 

screen = OpenScreen (&myNewScreen) ; 
if (screen != NULL) 

{ 

/* Indicate that the rastport is double buffered. */ 
screen->RastPort .Flags = DBUFFER; 

runDBuff (screen, myBitMaps); 

CloseScreen (screen) ; 

} 
freeBitMaps (myBitMaps, SCR DEPTH, SCR WIDTH, SCR HEIGHT); 



CloseLibrary (Gf xBase) ; 

} 

CloseLibrary (IntuitionBase) ; 

} 
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/* 

** setupBitMaps ( ) : allocate the bit maps for a double buffered screen. 

*/ 

struct BitMap ** setupBitMaps (LONG depth, LONG width, LONG height) 

{ 

/" this must be static -- it cannot go away when the routine exits. */ 
static struct BitMap *myBitMaps [2] ; 

myBitMaps [0] = (struct BitMap *) AllocMem ( (LONG) sizeof (struct BitMap), MEMF_CLEAR) ; 
if (myBitMaps [0] != NULL) 

{ 

myBitMaps[l] = (struct BitMap *) AllocMem( (LONG) sizeof (struct BitMap), MEMF_CLEAR) 
if (myBitMaps [1] != NULL) 

{ 

InitBitMap (myBitMaps [0] , depth, width, height); 
InitBitMap (myBitMaps [1] , depth, width, height); 

if (NULL != setupPlanes (myHitMaps [0] , depth, width, height)) 

{ 

if (NULL != setupPlanes (myBitMaps [1) , depth, width, height)) 
return (myBitMaps) ; 

freePlanes (myBitMaps [O] , depth, width, height); 

} 

FreeMem (myBitMaps [1) , (LONG) sizeof (struct BitMap)); 



} 



} 

FreeMem (myBitMaps [0] , (LONG) sizeof (struct BitMap)); I return(NULL) 



/* 

** runDBuff () : loop through a number of iterations of drawing into 
** alternate frames of the double-buffered screen. Note that the 
** object is drawn in color 1. 

*/ 

VOID runDBuff (struct Screen 'screen, struct BitMap **myBitMaps) 

{ 



WORD ktr, xpos, ypos ; WORD toggleFrame; 

toggleFrame = ; 

SetAPen (&( screen- >RastPort) , 1) ; 

for (ktr = 1; ktz < 200; ktr++) 

{ 

/* Calculate a position to place the object, these 

** calculations insure the object will stay on the screen 

** given the range of ktr and the size of the object. 

*/ 

xpos = ktr; 

if ( (ktr % 100) >= 50) 

ypos = 50 - (ktr % 50) ; 

else 

ypos = ktr % 5 0; 

/* switch the bitmap so that we are drawing into the correct place */ 
screen- >RastPort .BitMap = myBitMaps [toggleFrame] ; 

screen- >ViewPort .RasInfo->BitMap = myBitMaps [toggleFrame] ; 

/* Draw the objects. 

** Here we clear the old frame and draw a simple filled rectangle. 

*/ 

SetRast (& (screen- >RastPort) , 0) ; 

RectFill (& (screen->RastPort) , xpos, ypos, xpos+100, ypos+100) ; 

/* updaLe the physical display to match the newly drawn bitmap. •/ 

MakeScreen (screen) ; /* Tell intuition to do its stuff. */ 

RethinkDisplay ( ) ; /* Intuition compatible MrgCop s LoadView */ 

/* it also does a WaitTOFO . */ 

/" switch the frame number for next time through */ 
toggleFrame *"= 1; ) ) 
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/* 

** f reeBitMaps ( ) : free up the memory allocated by setupBitMaps ( ) . 

*/ 

VOID f reeBitMaps (struct BitMap **myBitMaps, LONG depth, LONG width, LONG height) 

{ 

freePlanes (myBitMaps [0] , depth, width, height); 
freePlanes (myBitMaps [1] , depth, width, height); 

FreeMem (myBitMaps [0) , (LONG) sizeof (struct BitMap)); 
FreeMem (myBitMaps [1) , (LONG) sizeof (struct BitMap)); 
} 

/* 

** setupPlanes ( ) : allocate the bit planes for a screen bit map. 

*/ 

LONG setupFlanes (struct BitMap *bitMap, LONG depth, LONG width, LONG height) 

{ 

SHORT plane_num ; 

for (plane_num = 0; planenum < depth; plane_num++) 

{ 

bitMap->Planes [plane_num] = (PLANEPTR) AllocRaster (width, height); 
if (bitMap->Planes [plane_num] != NULL ) 

BltClear (bitMap->Planes [plane num] , (width / 8) * height, 1) ; 
else 

{ 

freePlanes (bitMap, depth, width, height); 

return (NULL) ; 
} 
} 
return (TRUE) ; 



/* 

** freePlanesO : free up the memory allocated by setupPlanes ( ) . 

*/ 

VOID freePlanes (struct BitMap *bitMap, LONG depth, LONG width, LONG height) 

{ 

SHORT plane num ; 

f or (plane_num = 0; plane num < depth; plane num++) 

{ 

if (bitMap->Planes [plane_num] != NULL) 

FreeRaster (bitMap->Planes [plane num], width, height); 

DUAL-PLAYFIELD SCREEN EXAMPLE 

This example shows how to create a dual-playfield display. Note that this technique is only valid for screen 
modes which support dual-playfield, do not try to convert other modes. 

Setting up dual playfield mode in the OpenScreenQ call is not the best method of obtaining a dual playfield 
viewport for a screen. It is better to open a standard screen, passing to Intuition (or letting Intuition create) only 
one of the playfield bitmaps (the front one). Next allocate and set up a second bitmap, its bitplanes, and a 
Raslnfo structure installing these into the new screen's viewport. Update the viewport modes to include DUALPF 
and call MakeScreen() and RethinkDisplay(). This method, shown in the example below, keeps Intuition 
rendering (gadgets, menus, windows) in a single playfield. 

/* dualplayf ield. c 

** Shows how to turn on dual-playfield mode in a screen. 

* * 

** SAS/C 5.10a 

** lc -bl -cfist -v -y dualplayf ield 

** blink FROM LIBrc.o dualplayf ield . o TO dualplayf ield LIB LIB :1c. lib LIB ramiga . lib 

*/ 

#define INTUI_V3 6_NAMES_ONLY 
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#include <exec/types . h> 
#include <exec/memory . h> 
#include <intuition/intuition.h> 
#include <graphics/displayinf o . h> 

#include <clib/exec_protos . h> 
#include <clib/intuition_protos . h> 
#include <clib/graphics protos.h> 

VOID doDualPF ( struct Window * ) ; 

BOOL installDualPF( struct Screen *, struct Rastlnfo * ) ; 

VOID drawSomething { struct RastPort * ) ; 

VOID handlelDCMP ( struct Window * ) ; 

VOID removeDualPF ( struct Screen *s ) ; 

struct Library * IntuitionBase; 
struct Library *Gf xBase; 

VOID main(int argc, char **argv) 

{ 

struct Window *win; 
struct Screen *scr; 

IntuitionBase = OpenLibrary ( "intuition. library" , 37) ; 
if (IntuitionBase != NULL) 

{ 

GfxBase = OpenLibrary ( "graphics . library" , 37); 
if (GfxBase != NULL) 

{ 

scr = OpenScreenTags (NULL, SA_Depth, 2, 

SA_DisplayID, HIRES_KEY, 
SA_Title, "Dual Playfield Test Screen", 



if ( scr != NULL ) 

{ 

win = OpenWindowTags (NULL, 



WA_Title, 

WA_IDCMP, 

WA_Width, 

WA_Height, 

WA_DragBar, 



"Dual Playfield Mode" 

IDCMP_CLOSEWINDOW, 

200, 

100, 

TRUE, 



WA_CloseGadget, TRUE, 
WA_CustomScreen, scr, 
TAG END) ; 



if ( win != NULL ) 



{ 



doDualPF (win) ; 
CloseWindow (win) ; 

CloseScreen (scr) ; 

} 

CloseLibrary (Gf xBase) ; 



} 



} 

CloseLibrary (IntuitionBase) 



** Allocate all of the stuff required to add dual playfield to a screen. 

*/ 

VOID doDualPF (struct Window *win) 

{ 

struct Screen *myscreen; 
struct Raslnfo *rinfo2; 
struct BitMap *bmap2 ; 
struct RastPort *rport2; 

myscreen = win->WScreen; /* Find the window's screen */ 

/* Allocate the second playfield' s rasinfo, bitmap, and bitplane */ 

rinfo2 = (struct Raslnfo *) AllocMem(sizeof (struct Raslnfo), MEMF_PUBLIC I MEMF_CLEAR) 

if ( rinfo2 != NULL ) 

} 
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/* Get a rastport, and set it up for rendering into bmap2 */ 

rport2 = (struct RastPort *) AllocMem(sizeof (struct RastPort), MEMF_PUBLIC ); 

if (rport2 != NULL ) 

{ 

bmap2 = (struct BitMap *) AllocMem(sizeof lstruct BitMap) , MEMF_PUBLIC I MEMF_CLEAR) 
if (bmap2 != NULL ) 

{ 

InitBitMap (bmap2 , 1, myscreen->Width, myscreen- >Height ) ; 

/* extra playfield will only use one bitplane here. */ 

bmap2->Planes [0] = (PLANEPTR) AllocRaster (myscreen->Width, myscreen- >Height ) ; 

if (bmap2->Planes [O] != NULL ) 



} 



InitRastPort (rport2) ; 

rport2->BitMap = rinf o2->BitMap = bmap2 ; 

SetRast (rport2, 0) ; 

if ( installDualPF (myscreen, rinf o2 ) ) 

{ 

/* Set foreground color; color 9 is color 1 for 

** second playfield of hi-res viewport 

*/ 

SetRGB4 (kmyscreen- >ViewPort , 9, 0, OxF, 0); 



drawSomething (rport2) ; 
handlelDCMP(win) ; 

removeDualPF (myscreen) ; 

} 

FreeRaster (bmap2->Planes (0] , myscreen- >Width, myscreen- >Height) 

} 

FreeMem (bmap2 , sizeof (struct BitMap) ) ; 

} 

FreeMem (rport2 , sizeof (struct RastPort)); 

} 

FreeMem (rinfo2 , sizeof (struct Raslnfo) ) ; 

} 
} 

/* 

** Manhandle the viewport: 

** install second playfield and change modes 

*/ 

BOOL installDualPF (struct Screen *scrn, struct Rastlnfo *rinfo2) 

{ 

ULONG screen_modeID; 
BOOL return code = FALSE; 

screen modelD = GetVPModelD (& (scrn->ViewPort) ) ; 
if ( screen modelD != INVALID ID ) 

{ 

/* you can only play with the bits in the Modes field 

** if the upper half of the screen mode ID is zero! ! ! 

*/ 

if ( (screen_modeID & OxFFFFOOOOL) == 0L ) 

{ 

returncode = TRUE; 

Forbid ( ) ; 

/* Install rinfo for viewport's second playfield */ 
scrn->ViewPort .Raslnfo- >Next = rinf o2 ; 
scrn->ViewPort .Modes |= DUALPF; 

Permit () ; 

/* Put viewport change into effect */ 

MakeScreen (scrn) ; 

RethinkDisplay ( ) ; 
} 
} 
return (return code) ; 
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/* 

** Draw some lines in a rast port. . .This is used to get some data into 
** the second playfield. The windows on the screen will move underneath 
** these graphics without disturbing them. 

*/ 

VOID drawSomething (struct RastPort *rp) 

{ 

int width, height; int r, c; 

width = rp->BitMap->BytesPerRow * 8; 
height = rp->BitMap->Rows ; 



SetAPen(rp, 1) ; 

for(r = 0; r < height; r += 40) 
{ 



for (c = 0; c < width; c += 40) 

{ 

Move (rp, 0L, r) ; 
Draw (rp, c, 0L) ; 
} 
} 
} 

/* 

** simple event loop to wait for the user to hit the close gadget 
** on the window. 

*/ 

VOID handleIDCMP( struct Window *win) 

{ 

BOOL done = FALSE; 

struct IntuiMessage 'message = NULL; 

ULONG class; 

ULONG signals; 

while ( ! done) 

{ 

signals = Wait(lL << win->UserPort->mp_SigBit) ; 
if (signals & (1L << win->UserPort->mp_SigBit) ) 

{ 

while ((Idone) && (message = (struct IntuiMessage *) GetMsg (win->UserPort) ) ) 

{ 

class = message->Class ; 

ReplyMsg ( (struct Message *)message); 

switch (class) 

{ 

case IDCMP_CLOSEWINDOW: 

done = TRUE ; 
break; 



} 
} 



} 



/* 

** remove the effects of installDualPF ( ) . 
** only call if installDualPF ( ) succeeded. 
*/ 
VOID removeDualPF (struct Screen *scrn) 

{ 

Forbid ( ) ; 

scrn->ViewPort .Raslnf o->Next = NULL; 
scrn->ViewPort .Modes &= ' DUALPF; 

Permit ( ) ; 

MakeScreen (scrn) ; 
RethinkDisplay ( ) ; 
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Other Screen Functions 



Other screen functions provided by Intuition control screen depth arrangement, screen movement, the 
screen title bar and provide a visual "error beep". 

SCREEN DEPTH ARRANGEMENT 



ScreenToFrontQ and ScreenToBack() make a screen either the frontmost or the backmost screen. If an 
application needs to render into a screen before the screen becomes visible to the user, the screen may be 
opened behind all other screens and later moved to the front when ready with ScreenToFront(). 

VOID ScreenToFront ( struct Screen * ) 
VOID ScreenToBack ( struct Screen * ) 

Depth control of screens is also available through the depth arrangement gadget in the screen's title bar or 
through keyboard shortcuts. The N key with the Left-Amiga Qualifier moves the Workbench screen to 
front. The M key with the Left-Amiga Qualifier moves the frontmost screen to back. Repeated selection of 
Left-Amiga-M will cycle through available screens. These keys are processed through the keymap and will 
retain their value even if the key location changes. 

SCREEN MOVEMENT AND SCROLLING 

The MoveScreen() function moves the screen origin by the number of pixels specified in dx and dy. 

VOID MoveScreen ( struct Screen *myscreen, WORD dx, WORD dy ) 

Calls to MoveScreen() are asynchronous; the screen is not necessarily moved upon return of this function. 
If the calls happen too quickly, there may be unexpected results. One way to pace these calls is to call the 
function one time for each IDCMPJNTUITICKS event. 

Screen movement is also available through the screen's drag gadget in the title bar and through a 
keyboard/mouse shortcut. Left-Amiga with the select button of the mouse anywhere within the screen will 
drag the screen (even if the title bar is totally concealed by a window). Dragging a screen down will reveal 
any screen(s) behind it. Screens are never revealed to the left, right or bottom of another screen. 

Additionally, oversized screens may be moved with the new autoscroll feature of Release 2. With 
autoscroll, the screen is automatically scrolled as the pointer reaches one of the edges of the display. 
Autoscroll only works on the active screen. 

Another screen movement feature added in Release 2 is screen menu snap. When a screen much larger than 
the viewing area is scrolled such that the upper left corner is not visible (scrolled down or to the right), menus 
may could be out of the visible portion of the screen. To prevent this, menu snap moves the screen to a position 
where the menus will be visible before rendering them. The screen appears to snap to the home position as the 
menus are selected, moving back when the operation is complete. If the Left-Amiga Qualifier is held when the 
menus are selected then the screen will remain in the home position when the menu button is released. 
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The Intuition preferences editor, IControl, allows the user to change a number of Intuition features. Some of these 
features include the ability to globally disable menu snap, and to change the select qualifier for dragging the 
screen. See the User's Manual for more information on Preferences editors. 



MISCELLANEOUS SCREEN FUNCTIONS 

Three other functions used with screens are DisplayBeep(), ShowTitle() and GetScreenDataQ. DisplayBeep() 
flashes the screen colors to inform the user of an error or problem. 

VOID DisplayBeep ( struct Screen *myscreen ) 

Since not all users will have speakers attached to the system, DisplayBeepQ can be used to provide a visible 
bell. DisplayBeep() can beep any single screen or, if myscreen is set to NULL, all screens. 

ShowTitle() determines whether the screen's title bar will be displayed in front of or behind any backdrop 
windows on the screen. 

VOID ShowTitle ( struct Screen *myscreen, BOOL inf ront ) 



By default, the screen's title bar is set to display in front of backdrop windows. Call this function with infront set to 
FALSE to put the screen title bar behind backdrop windows. This can also be set when the screen is opened with 
the SA_ShowTitle tag. 

Under 1 .3 (V34) and earlier versions of the Amiga OS, applications used the GetScreenDataQ to get a copy of 
the Workbench Screen structure in order to examine its attributes. 

success = BOOL GetScreenData ( APTR buffer, UWORD bufsize, UWORD type, struct Screen 
*scr) 

If successful, GetScreenDataQ copies a given Screen structure to a buffer supplied by the application. A copy of 
the Workbench Screen data can be obtained without knowing its location in memory using GetScreenData(buf, 
sizeof(struct Screen), WBENCHSCREEN, NULL). However, for Release 2 and later versions of the operating 
system, this function may return some false information about the Workbench screen. This false screen 
information helps prevent older applications that used the call from malfunctioning when run in a Release 2 
system that has Workbench set up with one of the newer modes. 

Applications that want to get information on the Workbench screen should use GetScreenDataQ when run under 
1 .3 and LockPubScreen() when run under Release 2. For more about LockPubScreen() and Workbench, see 
the section on "Public Screen Functions" earlier in this chapter. 
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Function Reference 



The following are brief descriptions of the Intuition functions that relate to the use of Intuition screens. See the 
Amiga ROM Kernel Reference Manual: Includes and Autodocs for details on each function call. 

Table 3-10: Functions for Intuition Screens 

Function Description 

OpenScreenTagList() Open a screen. 

OpenScreenTags() Alternate calling sequence for OpenScreenTagList(). 

OpenScreen() Pre-V36 open screen function. 

CloseScreen() Close an open screen. 

MoveScreen() Change the position of an open screen. 

ScreenToBack() Move a screen behind all other screens. 

ScreenToFront() Move a screen in front of all other screens. 

ShowTitle() Show the screen in front of through backdrop windows. 

GetScreenDrawlnfoQ Get the Drawlnfo information for an open screen. 

FreeScreenDrawlnfo() Free the Drawlnfo information for a screen. 

QueryOverscan() Find overscan information for a specific display type. 

LockPubScreenQ Obtain a lock on a public screen. 

UnlockPubScreenQ Release a lock on a public screen. 

NextPubScreen() Return the name of the next public screen in the list. 

PubScreenStatus() Make a public screen private or private screen public. 

LockPubScreenListQ Lock the public screen list (for a public screen utility). 

UnlockPubScreenListQ Unlock the public screen list. 

SetDefaultPubScreen() Change the default public screen. 

SetPubScreenModes() Establish global public screen behaviour. 

GetDefaultPubScreen() Copies the name of the default public screen to a buffer. 

OpenWorkBenchQ Open the Workbench screen, if closed. 

CloseWorkBenchQ Close the Workbench screen, if possible. 

WBenchToBack() Move the Workbench screen behind all other screens. 

WBenchToFrontO Move the Workbench screen in front of all other screens. 

GetScreenData() Pre-V36 way to return information on an open screen. 

ViewAddress() Return the address of a screen's View. 

ViewPortAddress() Use &screen->ViewPort instead. 

MakeScreen() Low level screen handling-rebuild Copper list. 

RethinkDisplayQ Low level screen handling-incorporate Copper list changes. 



RemakeDisplay() MakeScreen() for all screens, then RethinkDisplay(). 
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Chapter 4 

INTUITION WINDOWS 



This chapter provides a general description of windows: how to open windows and define their characteristics; 
how to get the system gadgets for shaping, moving, closing, and depth arranging windows; how to handle 
window I/O; and how to preserve the display when windows get overlapped. 



About Windows 



Windows are rectangular display areas that open on screens. The window acts as a virtual terminal allowing a 
program to interact with the user as if it had the entire display all to itself. 

Each window opens on a specific screen and takes certain characteristics, such as resolution, colors and 
display attributes, from that screen. These values cannot be adjusted on a window by window basis. Other 
window characteristics such as the text font are inherited from the screen but can be changed. 

An application may open several windows at the same time on a single screen. The Workbench and other 
public (shareable) screens allow windows opened by different applications to coexist on the same screen. 

Windows are moveable and can be positioned anywhere within the screen on which they exist. Windows may 
also have a title and borders containing various gadgets for controlling the window. 

WINDOW SYSTEM GADGETS 

Each window may have a number of system gadgets which allow the user to control .window size, shape and 
arrangement. These gadgets are: the drag bar, the depth gadget, the sizing gadget, the zoom gadget and the 
close gadget. 

The drag bar allows the user to change the position of the window with respect to the screen. The drag bar is 
in the top border of a window and occupies any space in the top border that is not used by other gadgets. The 
window may be dragged left, right, up and down on the screen, with the limitation that the entire window must 
remain within the screen's boundaries. This is done by positioning the pointer over the title bar, selecting the 
window and dragging to the new position. Window drag may be cancelled by pressing the right mouse button 
before the drag is completed. 
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The depth gadget allows the user to depth arrange a window with respect to other windows on the screen. 
The depth gadget is always positioned in the upper fight corner of the window. Clicking the depth gadget will 
move the frontmost window behind all other windows. If the window is not the frontmost, it will be moved to the 
front. Selecting the depth gadget with the Shift qualifier always moves the window to the back (behind other 
windows). 

The sizing gadget allows the user to change the size of the window. Sizing is subject to minimum and 
maximum values set by the application. Width and height are independent in a sizing operation. The sizing 
gadget is always positioned in the lower fight corner of the window. It allows the user to drag this corner of the 
window to a new position relative to the upper left corner of the window, thus changing the width and height of 
the window. Window sizing using the sizing gadget may be cancelled by pressing the right mouse button 
before the size is completed. 

The zoom gadget allows the user to quickly alternate between two preset window size and position values. 
The zoom gadget is always placed immediately to the left of the depth gadget. If there is no depth gadget on 
the window, the zoom gadget will still appear next to where the depth gadget would have been. 

The close gadget performs no direct action on the window, rather it causes Intuition to send a message to the 
application to close the window. This allows the application to perform any required processing or to warn the 
user before it closes the window. The close gadget is always positioned in the upper left corner of the window. 

THE ACTIVE WINDOW 

There is only one window in the system active at any time. The active window receives all user input, including 
keyboard and mouse events. This is also known as the input focus, as all input is focused at this single point. 
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Some areas of the active window are displayed more boldly than those on inactive windows. The active 
window's borders are filled in with a color which is designed to stand out from the background while inactive 
windows have their borders filled with the background color. The specific coloring of active and inactive 
windows is dependent on the screen on which the window is opened. See the section "Drawlnfo and the 3D 
Look" in the "Intuition Screens" chapter for more information. 

Windows have two optional tides: one for the window and one for the screen. The window tide appears in the 
top border of the window, regardless of whether the window is active or inactive. The window's screen rifle 
appears in the screen's title bar only when the window is active. This gives the user a secondary clue as to 
what application is active in the screen. 

The active window's menus are displayed on the screen when the fight mouse button (the menu button ) is 
pressed. If the active window has no menus, then none will be displayed. 

Each window may also have its own mouse-pointer image. Changing the active window will change the 
pointer to the one currently set for the new active window. 

Basic Window Structures and Functions 

This section introduces the basic data structures and functions an application uses to create an Intuition 
window. Intuition uses the Window data structure defined in <intuition/intuition.h> to represent windows. Most 
of Intuition's window functions use this structure in some way. Other related structures used to create and 
operate windows are summarized in Table 4-1 . 

Table 4-1 : Data Structures Used with Intuition Windows 

Structure Name Description Defined in Include File 

Windows Main Intuition structure that defines a window <intuition/intuition.h> 

Tagltem General purpose parameter structure used to set up <utility/tagitem.h> 

windows in V37 

NewWindow Parameter structure used to create a window in V34 <intuition/intuition.h> 

ExtNewWindow An extension to the NewWindow structure used in <intuition/intuition. h> 



V37 for backward compatibility with older systems 
Layer A drawing rectangle that clips graphic operations <graphics/clip.h> 

falling within its boundaries 
RastPort General purpose handle used for graphics library < graphics/rastport.h> 

drawing operations. 

Intuition's window system relies on the layers library and graphics library to implement many of its features. 
The Window structure is closely related to the Layer structure defined in <graphics/clip.h> and the RastPort 
structure defined in <graphics/rastport.h>. The system uses these structures to store drawing state data. In 
general, applications don't have to worry about the internal derails of these structures but use them instead as 
convenient handles, parsing them as arguments to lower-level functions. See the "Layers Library" and 
"Graphics Primitives" chapters for more information. 
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OPENING A WINDOW 

A window is opened and displayed by a call to one of the OpenWindow() functions: OpenWindow(), 
OpenWindowTagListO or OpenWindowTags() 

struct Window *OpenWindowTagList ( struct NewWindow *newWindow, struct Tagltem *tagList ) ; 
struct Window *OpenWindowTags ( struct NewWindow *newWindow, unsigned long taglType, ... ) ; 
struct Window *OpenWindow ( struct NewWindow *newWindow ) ; 

The type of window and its attributes are specified in NewWindow or Tagltem structures depending on which 
function is used. These functions all return a pointer to a new Window structure if they succeed. A NULL 
return indicates failure. 

OpenWindowTagListO and OpenWindowTags() are available only in Release 2 (V36) and later versions of 
the OS. For these functions, window attributes are specified in Tagltem structures which are paired data items 
specifying an attribute and its setting. (See the 'Utility Library' chapter for more information on Tagltems.) 

OpenWindow() is available in all versions of the OS. Window attributes can be specified using a NewWindow 
structure but only a limited set of window attributes are available this way. To support both the new window 
features of Release 2 and compatibility with older versions of the OS, use OpenWindow() with an extended 
version of the NewWindow structure named ExtNewWindow. See the WFLG_NW_EXTENDED flag 
description in the "Window Attributes" section below for more information on using OpenWindowQ with the 
extended NewWindow structure. 

Further references to OpenWindow() in this chapter will apply to all three functions. These calls are the only 
proper method for allocating a Window structure. The tag based versions are recommended for V36 and later 
versions of the OS. Use the ExtNewWindow structure with OpenWindow() to provide backward compatibility. 

OpenWindowTagListO Example 

Here's an example showing how to open a new window using the OpenWindowTagListO function with 
window attributes set up in a Tagltem array. 

;/* openwindowtags . c - Execute me to compile me with SAS C 5.10 

LC -bl -cfistq -v -y -J73 openwindowtags . c 

Blink FROM LIB:c.o, openwindowtags . o TO openwindowtags LIBRARY LIB : LC . lib , 

LIB: Amiga. lib quit 

* * 

** openwindowtags . c - open a window using tags. 
*/ 

#define INTUI _V3 6_NAMES_ONLY 
#include <exec/types .h> 



#include <intuition/intuition.h> 
#include <intuition/intuitionbase . h> 
#include <intuition/screens .h> 

#include <clib/execprotos .h> 
#include <clib/dos_protos .h> 
#include <clib/intitionprotos . h> 

ttifdef LATTICE 

lnt CXBRK(void) { return(O); } /* Disable Lattice CTRL/C handling */ 

int chkabort {void) { return (0} ; } /* really */ 

#endif 
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ttdefine MY_WIN_LEFT (20) 

ttdefine MY_WIN_TOP (10) 

#define MY_WIN_WIDTH (300) 

#define MY_WIN_HEIGHT (110) 

void handlewindowevents (struct Window *); 

struct Library *IntuitionBase; 

struct Tagltem wintags [] = 

{ 

{WALeft, MY_WIN_LEFT}, 

{ WATop , MY_WIN_TOP } , 

{WAWidth, MY_WIN_WIDTH}, 

{WAHeight, MY_WIN_HEIGHT} , 
{WACloseGadget,TRUE} , 

{WAIDCMP, IDCMPCLOSEWINDOW}, 

{ TAGDONE , NULL } , 

}; 

/, 

** Open a simple window using OpenWindowTagList ( ) 

,/ 

VOID main (int argc, char **argv) 

{ 

struct Window *win; 

/* these calls are only valid if we have Intuition version 37 or greater 
*/ 

IntuitionBase = OpenLibrary ( "intuition. library" , 37) ; 

if (IntuitionBase! =NULL) 

{ 

win = OpenwindowTagList (NULL, wintags); 
if (win==NULL) 

{ 

/* window failed to open */ 



else 
{ 



/* window successfully opened here */ 
handlewindowevents (win) ; 



CloseWindow (win) ; 

} 

CloseLibrary ( (struct Library *) IntuitionBase) 



} 

/* Normally this routine would contain an event loop like the one given 

** in the chapter "Intuition Input and Output Methods". Here we Just 

** wait for any messages we requested to appear at the Window's port. 

*/ 

VOID handlewindowevents (struct Window *win) 

{ 

WaitPort (win->UserPort) ; 



Setting Window Attributes 

Depending on which function is used to open a window, the window's attributes may be specified using 
Tagltems, or a NewWindow structure or an ExtNewWindow structure. In the code above, the window 
attributes are set up with an army of Tagltems: 

struct Tagltem wintags [] = 

{ 

{WA_Left, MY_WIN_LEFT} , 
{ WA_Top , MY_WIN_TOP } , 
{WA_Width, MY_WIN_WIDTH} , 
{WA_Height, MY_WIN_HEIGHT} , 
{WA_CloseGadget, TRUE}, 
{WA_IDCMP, IDCMPCLOSEWINDOW} , 
{ TAGDONE , NULL } , 



}; 
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These window attributes set the window's position (WA_Left, WA_Top) and size (WA_Width, WA_Height), 
request a close gadget on the window (WA_CloseGadget) and ask Intuition to send a message whenever the 
user activates the close gadget (WAJDCMP). 

Throughout this chapter window attributes are referred to by their Tagltem ID name (the name is always 
prefixed with "WA' '). See the section below on "Window Attributes" for a complete list. 

Old and New Flag Names. The names used for IDCMP flags and window flags have 
been changed under Release 2. IDCMP flag names are now preceded by "IDCMP_". 
Likewise window flag names are now preceded by "WFLG_". The old names (and their 
new equivalents) are listed in <intuition/iobsolete.h>. You may want to refer to this file if 
you are working with example cede written for V34 and older versions of the OS. 

CLOSING WINDOWS 

Call the CloseWindow() function to close a window, remove its imagery from the display, and clean up any 
system resources used by the window. Typically, you call CloseWindow() when Intuition informs you that the 
user has selected the window's close gadget but this is not a requirement nor does the window have to be 
active to be closed. 

void CloseWindow ( struct Window *window ) ; 
Pass this function a pointer to the Window structure returned by one of the OpenWindow() calls. 

If you call CloseWindow() on the active window, the previously active window (if available) will become the 
active window. If the previously active window has already closed, then the window active prior to that window 
will become the active window. (Applications should not rely on this behaviour. To make a specific window 
become active, call the ActivateWindow() function.) 

Intuition does not automatically close a window when the user selects the close window gadget. Instead, 



Intuition sends your program a message about the user's action. The program can then perform whatever 
cleanup is necessary before closing the window with the CloseWindow() function. 

WINDOWS AND SCREENS 

Windows may be opened on one of three screen types: a custom screen, a public screen or the Workbench 
screen. A custom screen is one created and controlled by your application. Once you have set up a custom 
screen, you may open a window on it directly by calling one of the three open window functions. 

To open a window on a custom screen, call OpenWindowTagList() (or OpenWindowTags()) with the 
WA_CustomScreen tag along with a pointer to the custom screen. This must be a pointer to a screen created 
by your application. For systems prior to Release 2, use the OpenWindowQ call with NewWindow.Type set 
to CUSTOMSCREEN and NewWindow.Screen set to a pointer to your custom screen. 

You may choose to open a window on an existing public (shareable) screen instead of setting up your own 
custom screen. Such windows are often referred to as visitor windows because they "visit" a screen managed 
by the system or another application. 
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For Workbench or other public screens that are not created and managed directly by your application, you 
must lock the screen before opening the window. This ensures that the screen remains open while your call to 
open the window is processed. One way to obtain a lock on a public screen is by calling the 
LockPubScreen() function (see the "Intuition Screens" chapter). 

Use WA_PubScreenName with NULL to open a visitor window on the default public screen (normally the 
Workbench screen). If a name is provided and the named screen exists, the visitor window will open on that 
named screen. In this case the system locks the named screen for you so there is no need to call 
LockPubScreenO directly. The open window call will fail if it cannot obtain a lock on the screen. If the 
WA_PubScreenFallBack tag is TRUE, the window will open on the default public screen when 
WA_PubScreenName can't be found. 

Another method to open a visitor window on a public screen is to use the WA_PubScreen tag along with a 
pointer to the Screen structure of the public screen obtained via LockPubScreenO. 

The application may also request the name of the "next" public screen, which allows windows to "jump" 
between public screens. This is done by closing the application window on the first screen and opening a new 
window on the next screen. (See the "Intuition Screens" chapter for more information on public and custom 
screens.) 

If no action is taken by the programmer to open the window on a specific screen, the window will open on the 
default public screen (normally the Workbench). This behaviour is shown in the above example using 
OpenWlndowTagLlst(). 

There are two global modes which come into play when a visitor window is opened on a public screen. If the 
global mode SHANGHAI is set, Workbench application windows will be opened on the default public screen. A 
second global mode, POPPUBSCREEN, forces a public screen to be moved to the font when a visitor window 
opens on it. These modes can be changed using SetPubScreenModes(), however, these should only be set 
according to the preferences of the user. 

Simple Window on a Public Screen Example 

;/* wlnpubscreen. c - Execute me to compile me with SAS C 5.10 

LC -bl -cfistq -v -y -J73 winpubscreen . c 

Blink FROM LIB:c.o, winpubs cr een . o TO winpubscreen LIBRARY LIB : LC . lib , 

LIB: Amiga. lib quit 

* * 

** winpubscreen. c 

** open a window on the default public screen (usually the Workbench screen) 

*/ 



#define INTUI_V3 6_NAMES_ONLY 

#include <exec/types . h> 
#include <intuition/intuition.h> 
#include <clib/exec_protos . h> 
#include <clib/intuition_protos .h> 

#ifdef 1 ATT ICE 

int CXBRK(void) { return(O); } /* Disable Lattice CTRL/C handling */ 

int chkabort (void) { return(O) ; } /* really */ 

ttendif 

struct Library *IntuitionBase; 

/* our function prototypes */ 

VOID handle window events (struct Window *win) ; 
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/* 

** Open a simple window On the default public screen, 

** then leave it open until the user selects the close gadget. 

*/ 

VOID main (int argc, char **argv) 

{ 

struct Window *test_window = NULL; 
struct Screen *test_screen = NULL; 

IntuitionBase = OpenLibrary ( "intuition. library" , 37) ; 
if (IntuitionBase) 

{ 

/* get a lock on the default public screen */ 
if (test_screen = LockPubScreen (NULL) ) 

{ 

/* open the window on the public screen */ 
test_window = OpenWindowTags (NULL, 

WA_Left, 10, WA_Top, 20, 

WA_Wtdth, 300, WA_Height, 100, 
WA_DragBar, TRUE, 
WA_CloseGadget, TRUE, 
WA_SmartRef resh, TRUE, 
WA_NoCareRef resh, TRUE, 
WA_IDCMP, IDCMP_CLOSEWINDOW, 
WA_Title, "Window Title", 
WA_PubScreen, test_screen, 
TAG_END) ; 

/* Unlock the screen. The window now acts as a lock on 
** the screen, and we do not need the screen after the 
** window has been closed. 
*/ 
UnlockPubScreen (NULL, testscreen) ; 

/* if we have a valid window open, run the rest of the 
** program, t~en clean up when done. */ 

if (testwindow) 

{ 

handle_window_events (test_window) ; 
CloseWindow (test_window) ; 
} 



CloseLibrary (IntuitionBase) ; 
} 
} 

/* 

** Wait for the user to select the close gadget. 

*/ 

VOID handle_window_events (struct Window *win) 

{ 

struct IntuiMessage *msg; 
BOOL done = FALSE; 

while ( ! done) 

{ 

/* We have no other ports of signals to wait on, 

** so we'll Just use WaitPort ( ) instead of Wait ( ) 

*/ 

WaitPort [win- >UserPort) ; 

while ( ( ! done) && {msg = (struct IntuiMessage 
*) GetMsg (win->UserPort) ) ) 

{ 

/* use a switch statement if looking for multiple event types 

*/ 

if (msg->Class == IDCMP_CLOSEWINDOW) 
done = TRUE; 

ReplyMsg ( (struct Message *)msg); 
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GRAPHICS AND TEXT IN WINDOWS 

Applications can call functions in both the graphics library and the Intuition library to render images, lines, text 
and other graphic elements in windows. The graphics library provides primitive operations such as area fill, 
line drawing, text and animation. 

The number of colors and the palette available in a window are defined by the screen in which the window 
opens. Applications should never change the palette of a screen unless the screen is a custom screen created 
by the application. 

Graphics rendered into the window should respect the drawing pens defined for the screen. See the section 
on "Drawlnfo and the 3D Look" in the "Intuition Screens" chapter for more information. 

Default window fonts come from one of two places, depending on the screen on which the window opens. The 
window title font is always taken from the screen font. If the screen is opened with a font specified, either by 
specifying the tag SA_Font or the variable NewScreen.Font, then Window.RPort->Font is taken from the 
screen's font. Otherwise, the window's RastPort font is taken from GfxBase->DefaultFont. This information is 
available to the application if it opened the screen. 

If the application did not open the screen, it has no way of knowing which font has been used for the window. 
Applications that require to know the window's font before the window is open must explicitly set the font 
(using SetFont()) for that window after opening it. In this case, the application may use any font it desires. It is 
recommended that applications use the screen's font if they support proportional fonts, and 
GfxBase->DefaultFont otherwise, as these fonts are generally the user's preference. 

Intuition also provides a minimal high level interface to some of the functions in the Graphics library. This 



includes calls to draw lines, text and images. See the chapter entitled "Intuition Images, Line Drawing and 
Text," for more information about using Intuition to render graphics. 

WINDOW DIMENSIONS 

The initial position and dimensions of the window are defined in the OpenWindowTagLis() call. These values 
undergo error checking before the window is actually opened on the screen. If the dimensions are too big, the 
window will fail to open. (Or, you can use the WA_AutoAdjust tag if you want Intuition to move or size your 
window to fit.) 

Maximum and minimum size values may also be defined, but are not required If the window does not have a 
sizing gadget. In setting these dimensions, bear in mind the horizontal and vertical resolutions of the screen in 
which the window will open. 

The maximum dimensions of the window are unsigned values and may legally be set to the maximum by 
using the value OxFFFF, better expressed as "'0' '. Using this value for the maximum dimensions allows the 
window to be sized to the full screen. 
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A Display Sized Window Example 

A full screen window is not always desirable. If the user is working on a large, scrolling screen, they may only 
want a window the size of the visible display. The following example calculates the visible area on a screen 
and opens a window in that area. The example assumes that the screen display clip is as large or larger than 
text overscan (OSCAN_TEXT) which is set by the user. The window is opened in the text overscan area, not 
within the actual display clip that is used for the screen. Use QueryOverscanO to find the standard overscan 
rectangles (display clips) for a screen. Use the graphics library call VideoControl() to find the true display clip 
of the screen (see the chapter on "Graphics Primitives" for more information on VideoControl()). The 
ViewPortExtra structure contains the display clip information. 

About Screen Coordinates. The screen's actual position may not exactly equal the 
coordinates given in the LeftEdge and TopEdge fields of the Screen structure. This is 
due to hardware constraints that limit the fineness of the positioning of the underlying 
constructs. This may cause a window which is opened in the visible pan of the screen to 
be incorrectly positioned by a small number of pixels in each direction. Sec the discussion 
of the screen's LeftEdge and TopEdge in the "Intuition Screens" chapter for more 
information. 

;/* visiblewindow. c - Execute me to compile me with SAS C 5.10 

LC -bl -cfistq -v -y -J73 visiblewindow. c 

Blink FROM LIB:c.o, visiblewindow. o TO visiblewindow LIBRARY LIB:LC.lib, 

LIB: Amiga. lib 

quit 

* * 

** open a window on the visible part of a screen, with the window as large 

** as the visible part of the screen. It is assumed that the visible part 

** of the screen is OSCANTExT, which how the user has set their preferences. 

,/ 

#define INTUI_V3 6_NAMES_ONLY 

#include <exec/types . h> 
#include <intuition/intuition.h> 
#include <intuition/intuitionbase . h> 
#include <graphics/displayinf o . h> 
#include <clib/exec_protos . h> 
#include <clib/intuition_protos .h> 
#include <clib/graphics_protos . h> 

#ifdef #LATTICE 



int CXBRK(Void) { return(O); } /* Disable Lattice CTRL/C handling */ 

int chkabort (void) { return(O); } /* really */ 

#endif 

/* Minimum window width and height: 

** These values should really be calculated dynamically given the size 

** of the font and the window borders. Here, to keep the example simple 

** they are hard- coded values. 

*/ 

#define MIN_WINDOW_WIDTH (100) 
#define MIN_WINDOW_HEIGHT (50) 

/* minimum and maximum calculations .. .Note that each argument is 

** evaluated twice (don't use max (a++, foo (c) ) ) . 

,/ 

#define max(a,b) ( (a) > (b) ? (a) : (b) ) 

#define min(a,b) ( (a) <= (b) ? (a) : (b) ) 

struct Library *IntuitionBase; 
struct Library *Gf xBase ; 

/* our function prototypes */ 

VOID handlewindowevents (struct Window *win) ; 

VOID fullscreen (VOID) ; 
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/* 

** open all the libraries and run the code. Cleanup when done. 

*/ 

VOID main (int argc, char **argv) 

{ 

/* these calls are only valid if we have Intuition version 37 or greater 

*/ 

if (GfxBase = OpenLibrary ( "graphics . library" , 37) ) 

{ 

if (IntuitionBase = OpenLibrary ( "intuition. library" , 37) ) 

{ 

fullscreen ( ) ; 

CloseLibrary (IntuitionBase) ; 

} 

CloseLibrary (GfxBase) ; 

} 
} 

/* 

** Open a window on the default public screen, then leave it open until the 
** user selects the close gadget. The window is full-sized, positioned in the 
** currently visible OSC/AN_TEXT area. 
*/ 

VOID fullscreen (VOID) 
( 

struct Window *testwindow; 

struct Screen *pubscreen; 

struct Rectangle rect; 

ULONG screen_modeID; 

LONG width, height, left, top; 

left = 0; /* set some reasonable defaults for left, top, width and 



height . ' / 

top =0; /* we'll pick up the real values with the call to 
QueryOverscan ( ) . */ 

width = 64 0; 

height= 2 0; 

/* get a lock on the default public screen */ 
if (NULL 1= (pubscreen = LockPubScreen (NULL) ) ) 

{ 

/* this technique returns the text overscan rectangle of the screen that 
we 

** are opening on. If you really need the actual value set into the 
display 

** clip of the screen, use the VideoControl ( ) command of the graphics 
library 

** to return a copy of the ViewPortExtra structure. See the Graphics 

** library chapter and Autodocs for more details. 

** GetVPModelD () is a graphics call... 
*/ 

screen_modeID = GetVPModelD (&pubscreen->ViewPort) ; 
if (screen_modeID != INVALID_ID) 

{ 

if (QueryOversean(screenmodeID, Srect, OSCAN_TEXT) 

{ 

/* make sure window coordinates are positive or zero */ 
left = max ( , -pubscreen- >Lef tEdge) ; 
top = max(D, -pubscreen- >TopEdge ) ; 

/* get width and height from size of display clip */ 
width = rect.MaxX - rect.MinX + 1; 
height = rect.MaxY - rect.MinY + 1; 

/* adjust height for pulled-down screen (only show visible part) */ 
if (pubscreen- >TopEdge > 0) 

height -= pubscreen- >TopEdge; 

/* insure that window fits on screen */ 
height = min[height, pubscreen- >Height ) ; 
width = min (width, pubscreen- >Width) ; 

/* make sure window is at least minimum size */ 

width = max (width, MINWINDOWWIDTH) ; 

height = max (height, MINWINDOWHEIGHT) ; 
} 
} 
/* Open the window on the public screen */ 
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test_window = OpenWindowTags (NULL, 

WA_Left, left, WA_Width, width, 

WA_Top, top, WA_Height, height, 

WA_CloseGadget, TRUE, 

WA_IDCMP, IDCMP_CLOSEWINDOW, 

WA_PubScreen, pubscreen, 

TAG_END) ; 



/* unlock the screen. The window now acts as a lock on the screen- 

** and we do not need the screen after the window has been closed. 

*/ 

UnlockPubScreen (NULL, pubscreen) ; 

/* if we have a valid window open, run the rest of the 

** program, then clean up when done. 

*/ 

if (testwindow) 

{ 

handle_window_events (testwindow) ; 
Closewindow (testwindow) ; 



} 



} 



/* 

** Wait for the user to select the close gadget. 

*/ 

VOID handle_window_events (struct Window *win) 

{ 

struct IntuiMessage *msg; 
BOOL done = FALSE; 

while ( ! done) 

{ 

/* we only have one signal bit, so we do not have to check which 

** bit(s) broke the Wait() (i.e. the return value of Wait) 

*/ 

Wait(lL << win->UserPort->mp_SigBit) ; 

while ( (! done) && (msg = (struct IntuiMessage 
*) GetMsg (win->userPort) ) ) 

{ 

/* use a switch statement if looking for multiple event types 

*/ 

if (msg->Class == IDCMP_CLOSEWINDOW) 
done = TRUE; 

ReplyMsg ( (struct Message *)msg); 



WINDOW BORDER DIMENSIONS 

Intuition automatically draws a border around a window unless directed otherwise, such as by setting the 
WFLG_BORDERLESS flag. Borderless windows may not have a window title or gadgets in the border (this 
includes the standard system gadgets). Otherwise they won't come out properly borderless. 

The size of the border of an open window is available in the Window structure variables BorderLeft, 
BorderTop, BorderRight and BorderBottom. Intuition fills these in when the window is opened. To calculate 
the window border sizes before the window is opened you use information in the Screen structure as shown in 
the next listing. 

Gadgets Can Change Border Sizes. The following calculations do not take application 
border gadgets into account. If the program adds gadgets into the window's borders, 
Intuition will expand the borders to hold the gadgets. 
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if (NULL != (screen = LockPubScreen (NULL) ) ) 

{ 

top_border = screen- >WBorTop + screen- >Font->taYSize 

left_border = screen- >WBorLef t ; 

right_border = screen- >WBorRlght ; 
bottom_border = screen- >WBorBottom; 



UnlockPubScreen (NULL, screen) 



} 



/* if the sizing gadget is specified, then the border size must 
** be adjusted for the border containing the gadget. This may 
** be the right border, the bottom border or both. 

* * 

** We are using fixed values. There is currently no system- approved 
** method of finding this information before the window is opened. 
** If you need to know these sizes BEFORE your window is opened, 
** use the fixed values below. Otherwise, use Window- >BorderRight, 
** etc. AFTER you have opened your window. 
*/ 

/* values for non-lo-res screen */ 

right_border = 18; /* if sizing gadget in right border */ 

bottom_border = 10; /* if sizing gadget in bottom border */ 

/* values for lo-res screen */ 

right_border = 13; /* if sizing gadget in right border */ 

bottom_border = 11; /* if sizing gadget in bottom border */ 

Use the border sizes to position visual elements within the window. Coordinates may be offset into the window 
by the size of the top and left borders, for instance (x, y) becomes (x + BorderLeft, y + BorderTop). This may 
look clumsy, but it offers a way of avoiding a GimmeZeroZero window, which, although much more convenient 
to use, requires extra memory and degrades performance. 

The right and bottom border values specify the width of these borders. The area within the borders of a 
window is defined as (BorderLeft, BorderTop) to (Width - 1 - BorderRight, Height - 1 BorderBottom). The 

calculations subtract one from the height and width of the windows as positions count from zero, but 
dimensions count from one. 

The window title bar is only available if one or more of the following is specified: window title, window drag 
gadget, window depth gadget, window close gadget or window zoom gadget. If none of these are specified, 
the top border will be much narrower. 

Application gadgets may be added to the window border by setting a flag in the Gadget structure. A special 
flag must additionally be set to place gadgets into the borders of GimmeZeroZero windows. See the chapter 
"Intuition Gadgets," for more information about gadgets and their positioning. (Borderless windows have no 
visible border outlines and gadgets should not be placed in their borders.) 

CHANGING WINDOW SIZE LIMITS 

To change the sizing limits after the window has been opened, call WindowLimits() with the new values. 

BOOL WindowLimits ( struct Window *window, long widthMin, long heightMin, 
unsigned long widthMax, unsigned long heightMax ) ; 

To maintain the current dimension, set the corresponding argument to 0. Out of range numbers are ignored. If 
the user is currently sizing the window, new limits take effect after the user releases the select button. 
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Communicating with Intuition 



Intuition can notify an application when the user moves the mouse, makes a menu choice, selects an 
application gadget or changes the window's size. To find out about user activity from Intuition, there are two 
methods: 

Use the Intuition Direct Communications Message Port (IDCMP) system. Input events are received 
as standard Exec messages at a port Intuition creates for your window. 

Use the console.device to receive all input events as character sequences. 



THE IDCMP 

The IDCMP gives an application convenient access to many types of user input events through the Exec 
message and port system. Intuition input event messages include mouse and keyboard activity as well as high 
level events from menus and gadgets. 

With the IDCMP, you specify the input events you want to know about when you open the window. The input 
events are specified with one or more of the IDCMP flags in <intuition/intuition.h>. Use the flags with the 
WAIDCMP tag for the OpenWindowTagListO (or OpenWindowTagsQ) function. Or, set the flags in 
NewWindow.lDCMPFIags for the OpenWindowO function. If any IDCMP flags are set when the window is 
opened, Intuition automatically creates a message port for you to receive messages about user activity. If 
NULL is specified for IDCMP flags, no port is created. For more information on receiving messages from 
Intuition, see the IDCMP section in the chapter "Intuition Input and Output Methods." 

THE CONSOLE DEVICE 

An alternative to the message system used by the IDCMP is the console device. The console device gives 
your application input data translated to ASCII characters or ANSI escape sequences. Raw (untranslated) 
input is also available through the console device as ANSI escape sequences. 

The console device also provides for convenient output of control codes and non-proportional (mono-spaced) 
text to the window. Output is character based, and includes capabilities such as automatic line wrapping and 
scrolling. The console device automatically formats and interprets the output stream. Output is kept within the 
window boundaries automatically so the application need not worry about overwriting the border (no 
GimmeZeroZero window required). 

The console device must be opened by the application before it is used. See the chapter entitled "Intuition 
Input and Output Methods" or refer to the "Console Device" chapter of the Amiga ROM Kernel Reference 
Manual.' Devices tor more information about using the console device with your Intuition windows. 

THE IDCMP AND THE ACTIVE WINDOW 

On the Amiga, all input is directed to a single window called the active window. In general, changing the active 
window should be left up to the user. (The user activates a window by pressing the select button while the 
pointer is within the window boundaries.) If the active window is changed, the user may be confused if the 
change was not performed at their direction. Hence, new windows should be activated only when they open 
as a direct and synchronous response to the user's action. Existing windows should almost never be activated 
by the application. 
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An application can learn when one of its windows is activated or deactivated by setting the IDCMP flags 
IDCMP_ACTIVEWINDOW and IDCMPJNACTIVEWINDOW. When these flags are specified, the program will 
receive a message each time the user activates the window or causes the window to become inactive by 
activating some other window. 

The application may specify that a window is to become active when it opens. This is done with the 
WAActivate tag or by setting WFLG_ACTIVATE in NewWindow.Flags when the window is opened. 

The application may also activate an existing window. This is done by calling the ActivateWindow() function, 
which will activate the window as soon as possible. Try to use this function only in response to user action 
since it may cause a shift in the input focus: 

LONG ActivateWindow ( struct Window *window ); 

This function call may have its action deferred. Do not assume that the selected window has become active 
when this call returns. Intuition will inform the application when this window has become active by sending an 
IDCMP_ACTIVEWINDOW message. Getting this message is the only supported way of tracking the activation 
status of your windows. 

THE IDCMP AND GADGETS 

One way for a user to communicate with a program running under Intuition is through the use of gadgets. 
There are two basic kinds of gadgets: system gadgets, which are predefined and managed by Intuition, and 
application gadgets. 

System Gadgets 

System gadgets on each window provide the user with the ability to manage the following aspects of the 
window: size, position and depth. These gadgets are managed by Intuition and the application does not need 
to take any action for them to operate properly. An additional system gadget is provided for the "close window" 
function. The close action is not directly managed by Intuition; selecting the close gadget will simply send a 
message to the application, which is responsible for closing the window. 

All of these gadgets are optional, and independent of each other. The graphic representations of these 
gadgets are predefined, and Intuition always displays them in the same standard locations in the window 
borders. 

The application may choose to be notified when the window changes size, or it may choose to control the 
timing of the sizing of the window. Controlling the timing of sizing operations is done through the use of the 
IDCMP_SIZEVERIFY message. IDCMP_SIZEVERIFY messages time out if the application does not respond 
fast enough. When these an IDCMP_SIZEVERIFY message times out the window sizing operation is 
cancelled by Intuition. 

No information is available to the program on user changes to the depth arrangement of a window. However a 
refresh message will be sent if part of the window needs to be redrawn as a result of a change to the depth 
arrangement. 

Notification of changes to the position of the window or the size of the window are available through the 
IDCMP_CHANGEWINDOW and IDCMP_NEWSIZE flags. The application specifies the initial size, the 
maximum and minimum limits for sizing, and whether the sizing gadget is contained in the right border, 
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bottom border or both borders. (See the section on "Border Dimensions" for information on how the 



specification of the sizing gadget affects the border sizes.) 

The drag gadget has no imagery other than the implicit imagery of the title bar. Setting the window title does 
not interfere with drag gadget operation, nor does the drag gadget interfere with the display of the window tide. 

Application Gadgets 

The application may place gadgets in windows to request various kinds of input from the user. These gadgets 
may be specified in the OpenWindowTagList() call, or they may be created and added to the window later. 
For details about creating and using gadgets, see the chapters on "Intuition Gadgets" and the "GadTools 
Library". 



Window Types 



There are three special window types: Backdrop, Borderless and GimmeZeroZero. Backdrop windows stay 
anchored to the back of the display. Borderless windows have no borders rendered by Intuition. 
GimmeZeroZero windows provide clipping to protect the borders from graphics rendered into the window. 

These window types can be combined, although the combinations are not always useful. For instance, a 
borderless, backdrop window can be created; however, a borderless, GimmeZeroZero window does not make 
sense. A window is not required to be any of these types. 

BACKDROP WINDOW TYPE 

Backdrop windows open behind all other non-backdrop windows, but in front of other backdrop windows that 
might already be open. Depth arrangement of a backdrop window affects the order of the window relative to 
other backdrop windows, but backdrop windows always stay behind all non-backdrop windows. No amount of 
depth arrangement will ever move a non-backdrop window behind a backdrop window. 

The only system gadget that can be attached to a backdrop window is the CloseWindow gadget. Application 
gadgets are not restricted in backdrop windows. 

Backdrop windows may often be used in place of drawing directly into the display memory of a custom screen. 
Such a technique is preferred, as backdrop windows are compatible with the Intuition windowing system. 
Using a backdrop window eliminates the danger of writing to the screen memory at a "bad" time or at the 
wrong position and overwriting data in a window. 

To provide a full screen display area that is compatible with the windowing system, create a full sized, 
borderless, backdrop window with no system gadgets. Use the ShowTitleQ call to hide or reveal the screen's 
title bar, as appropriate. See the Amiga ROM Kernel Reference Manual: Includes and Autodocs for a 
complete list of arguments for ShowTitle(). 

Backdrop windows are created by specifying the WFLG_BACKDROP flag or the WA_BACKDROP tag in the 
OpenWindowTagList() call. 
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BORDERLESS WINDOW TYPE 

The borderless window type has no borders rendered by Intuition. Such a window will have no visual 
delineation from the rest of the display. Be aware that a Borderless window which does not cover the entire 
display may cause visual confusion for the user. When using a borderless window that does not cover the 
entire display, the application should provide some form of graphics to replace the borders provided by 
Intuition. 



In general, none of the system gadgets or the window tide should be specified for a borderless window, as 
they may cause at least part of the border to be rendered. 

A typical application of a borderless window is to simulate graphics drawn directly into the screen, while 
remaining compatible with windows and menus. In this case, the application will often create a full sized, 
borderless, backdrop window. 

Use the WFLG_BORDERLESS flag or the WA_Borderless tag to get this window type. 

GIMMEZEROZERO WINDOW TYPE 

GimmeZeroZero windows provide a window border layer separate from the main (inner) window layer. This 
allows the application to freely render into the window without worrying about the window border and its 
contents. 

System gadgets and the window title are placed in the border layer. Application gadgets go into the inner 
window by default, but may be placed in the border. To position application gadgets in the border layer, the 
GTYP_GZZGADGET flag and the appropriate Gadget border flag must be set in the Activation field of the 
Gadget. 

The top left coordinates of the inner window are always (0,0), regardless of the size or contents of the border, 
thus the name "GimmeZeroZero." The application need not take the border size into account when rendering. 
The inner window always begins at (0,0) and extends to (GZZWidth,GZZHeight). The GZZWidth and 
GZZHeight variables are available in the Window structure. 

The GZZMouseX and GZZMouseY variables provide the position of the mouse relative to the inner window. 
Note that the mouse positions in IDCMP_MOUSEMOVE events are always relative to the total window, even 
for GimmeZeroZero windows. 

Requesters in a GimmeZeroZero window are also positioned relative to the inner window. See the chapter 
entitled "Intuition Requesters and Alerts," for more information about requester location. 

To specify a GimmeZeroZero window, set the WFLG_GIMMEZEROZERO flag or WA_GIMMEZEROZERO 
tag in the OpenWindowTagList() call. 

WARNING! The GimmeZeroZero window uses more system resources than other window types 
because the window creates a separate layer for the border display. Using multiple 
GimmeZeroZero windows will quickly degrade performance in the positioning and sizing of 
windows. 

Applications should consider using regions as an alternative to GimmeZeroZero windows. See 
the "Layers Library" chapter, especially the lnstallClipRegion() function, for information on 
setting up regions to limit graphics display in the window. 
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Preserving the Window Display 

The layers library is what allows the display and manipulation of multiple overlapping rectangles, or layers. 
Intuition uses the layers library to manage its windows, by associating a layer to each window. 

Each window is a virtual display. When rendering, the application does not have to worry about the current 
size or position of its window, and what other windows might be partly or fully obscuring its window. The 
window's RastPort is the handle to the its virtual display space. Intuition and graphics library rendering calls 
will recognize that this RastPort belongs to a layer, and act accordingly. 

As windows are moved, resized, rearranged, opened, or closed, the on-screen representation changes. When 



part of a window which was visible now needs to appear in a new location, the layers library will move that 
imagery without involving the application. However, when part of a window that was previously obscured is 
revealed, or when a window is made larger, the imagery for the newly-visible part of the window needs to be 
redrawn. Intuition, through layers, offers three choices for how this is managed, trading off speed, memory 
usage, and application complexity. 

The most basic type of window is called Simple Refresh. When any graphics operation takes place in 
this kind of window, the visible pans are updated, but rendering to the obscured parts is discarded. 
When the window arrangement changes to reveal a previously obscured part of such a window, the 
application must refresh that area. 

Alternately, a window may be made Smart Refresh, which means that when rendering occurs, the 
system will not only update the visible parts of the window, but it will maintain the obscured parts as 
well, by using off-screen buffers. This means that when an obscured part of the window is revealed, 
the system will restore the imagery that belongs there. The application needs only to refresh parts of 
the window that appear when the window is made bigger. Smart Refresh windows use more memory 
than Simple Refresh windows (for the storage of obscured areas), but they are faster. 

The third kind of window is called SuperBitMap. In such a window, the system can refresh the 
window even when it is sized bigger. For this to work, the application must store a complete bitmap 
for the window's maximum size. Such a window is more work to manage, and uses yet more 
memory. SuperBitMap windows are used less often than the other two types. 

Intuition helps your application manage window refresh. First, Intuition will take care of redrawing the window 
border and any system and application gadgets in the window. Your application never has to worry about that. 
Second, Intuition will notify your application when it needs to refresh its window Coy sending the 
IDCMP_REFRESHWINDOW event). Third, Intuition provides functions that restrict your rendering to the 
newly-revealed (damaged) areas only, which speeds up your refresh rendering and makes it look cleaner. 

The Intuition, layers, and graphics libraries work together to make rendering into and managing windows easy. 
You obtain your windows through Intuition, which uses the Layers library to manage the overlapping, resizing, 
and re-positioning of the window layers. The layers library is responsible for identifying the areas of each 
window that are visible, obscured but preserved off-screen, or obscured and not preserved. The rendering 
functions in the graphics library and Intuition library know how to render into the multiple areas that layers 
library establishes. 
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Note that you may not directly manipulate layers on an Intuition screen. You cannot create your own layers on 
an Intuition screen, nor can you use the layers movement, sizing, or arrangement functions on Intuition 
windows. Use the corresponding Intuition calls instead. Some other Layers library calls (such as the locking 
calls) are sometimes used on Intuition screens and windows. 

DAMAGE REGIONS 

The layers library and Intuition maintain a damage region for each window, which is the part of the window 
whose imagery is in need of repair, or refreshing. Several things can add areas of the window to the damage 
region: 

Revealing an obscured part of a Simple Refresh window adds that area to the damage region 

Sizing a Simple or Smart Refresh window bigger along either axis adds the new area to the damage 
region 

Resizing a Simple or Smart Refresh window (smaller or bigger) adds the old and new border areas, 
and the areas occupied by certain gadgets (those whose position or size depend on window size) to 
the damage region. 



REFRESHING INTUITION WINDOWS 

When the user or an application performs an Intuition operation which causes damage to a window, Intuition 
notifies that window's application. It does this by sending a message of the class IDCMP_REFRESHWINDOW 
to that window's IDCMP. 

In response to this message, your application should update the damaged areas. Rendering proceeds faster 
and looks cleaner if it is restricted to the damaged areas only. The BeginRefresh/EndRefresh() pair achieve 
that. The application should call BeginRefresh() for the window, and then do its rendering. Any rendering that 
would have gone into undamaged areas of the window is automatically discarded; only the area in need of 
repair is affected. Finally, the application should call EndRefresh(), which removes the restriction on 
rendering, and informs the system that the damage region has been dealt with. Even if your application 
intends to do no rendering, it must at least call BeginRefresh()/EndRefresh(), to inform the system that the 
damage region is no longer needed. If your application never needs to render in response to a refresh event, it 
can avoid having to call BeginRefresh()/EndRefresh() by setting the WFLG_NOCAREREFRESH flag or the 
WA_NOCAREREFRESH tag in the OpenWindowTagList() call. 

Note that by the time that your application receives notification that refresh is needed, Intuition will have 
already refreshed your window's border and all gadgets in the window, as needed. Thus, it is unnecessary to 
use any of the gadget-refreshing functions in response to an IDCMP_REFRESHWINDOW event. 

Operations performed between the BeginRefresh()/EndRefresh() pair should be restricted to simple 
rendering. All of the rendering functions in Intuition library and Graphics library are safe. Avoid RefreshGList() 
or RefreshGadgets(), or you risk deadlocking the computer. Avoid calls that may lock the Layerlnfo or get 
complicated in Intuition, since BeginRefreshQ leaves the window's layer or layers locked. Avoid 
AutoRequest() and EasyRequestQ, and therefore all direct or indirect disk related DOS calls. See the 
"Intuition Gadgets" chapter for more information on gadget restrictions with BeginRefresh()/EndRefresh(). 
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Simple Refresh 

For a Simple Refresh window, only those pixels actually on-screen are maintained by the system. When part 
of a Simple Refresh window is obscured, the imagery that was there is lost. As well, any rendering into 
obscured portions of such a window is discarded. 

When part of the window is newly revealed (either because the window was just made larger, or because that 
pan used to be obscured by another window), the application must refresh any rendering it wishes to appear 
into that part. The application will learn that refresh is needed because Intuition sends an 
IDCMP_REFRESHWINDOW event. 

Smart Refresh 

If a window is of the Smart Refresh type, then the system will not only preserve those pixels which are actually 
on-screen, but it will save all obscured pixels that are within the current window's size. The system will refresh 
those parts of the window revealed by changes in the overlapping with other windows on the screen, without 
involving the application. However, any part of the window revealed through the sizing of the window must be 
redrawn by the application. Again, Intuition will notify the application through the IDCMP_REFRESHWINDOW 
event. 

Because the obscured areas are kept in off-screen buffers, Smart Refresh windows are refreshed faster than 
Simple Refresh windows are, and often without involving the application. Of course, for the same reason, they 
use more display memory. 

SuperBitMap Refresh 

The SuperBitMap refresh type allows the application to provide and maintain bitmap memory for graphics in 
the window. The bitmap can be any size as long as the window sizing limits respect the maximum size of the 
bitmap. 



SuperBitMap windows have their own memory for maintaining all obscured parts of the window up to the size 
of the defined bitmap, including those parts outside of the current window. Intuition will update all pans of the 
window that are revealed through changes in sizing and changes in window overlapping. The application 
never needs to redraw portions of the window that were revealed by sizing or positioning windows in the 
screen. 

SuperBitMap windows require the application to allocate a bitmap for use as off-screen memory, instead of 
using Intuition managed buffers. This bitmap must be as large as, or larger than, the inner window's maximum 
dimensions (that is, the window's outside dimensions less the border sizes). 

SuperBitMap windows are almost always WFLG_GIMMEZEROZERO, which renders the borders and system 
gadgets in a separate bitmap. If the application wishes to create a SuperBitMap window that is not 
GimmeZeroZero, it must make the window borderless with no system gadgets, so that no border imagery is 
rendered by Intuition into the application's bitmap. 
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INTUITION REFRESH EVENTS 

When using a Simple Refresh or a Smart Refresh windows, the program may receive refresh events, 
informing it to update the display. See the above discussion for information on when refresh events are sent. 

A message of the class IDCMP_REFRESHWINDOW arrives at the IDCMP, informing the program of the need 
to update the display. The program must take some action when it receives a refresh event, even if it is just 
the acceptable minimum action described below. 

On receiving a refresh event, BeginRefresh() must be called, then the program should redraw its display, 
and, finally, call EndRefresh(). The minimum required action is to call the BeginRefresh()/EndRefresh() pair. 
This allows Intuition and the Layers library keep things sorted and organized. 

OPTIMIZED WINDOW REFRESHING 

Bracketing the display updating in the BeginRefresh()/EndRefresh() pair automatically restricts all rendering 
to the "damaged" areas. 

void BeginRef resh ( struct Window *window ); 

void EndRefresh ( struct Window *window, long complete ) ; 

These functions makes sure that refreshing is done in the most efficient way, only redrawing those portions of 
the window that really need to be redrawn. The rest of the rendering commands are discarded. 

Operations performed between the BeginRefresh()/EndRefresh() pair should be restricted to simple 
rendering. All of the rendering functions in Intuition library and Graphics library are safe. Calls to 
RefreshGadgetsQ are not permitted. Avoid calls that may lock the Layerlnfo, or get complicated in Intuition, 
since BeginRefresh() leaves the window's layer or layers locked. Avoid AutoRequestQ, and therefore all 
direct or indirect disk related DOS calls. See the "Intuition Gadgets" chapter for more information on gadget 
restrictions with BeginRefresh()/EndRefreshO. 

Certain applications do not need to receive refresh events, and can avoid having to call BeginRefresh() and 
EndRefresh() by setting the WFLG_NOCAREREFRESH flag or the WA_NOCAREREFRESH tag in the 
OpenWindowTagList() call. 

The EndRefresh() function takes a boolean value as an argument (complete in the prototype above). This 
value determines whether refreshing is completely finished. When set to FALSE, further refreshing may be 
performed between subsequent BeginRefresh()/EndRefresh() pairs. Set the boolean to TRUE for the last 
call to EndRefresh(). 

It is critical that applications performing multiple BeginRefresh()/EndRefresh() pairs using 
EndRefresh(win, FALSE) hold layers locked through the entire process. The layer lock may only be released 



after the final call to EndRefresh(win,TRUE). See the "Layers Library" for more details. 

The procedures outlined in this section take care of refreshing what is inside the window. Another function 
named RefreshWindowFrame() refreshes window borders, including the title region and gadgets: 

void Ref reshWindowFrame ( struct Window *window ) ; 

Applications can use this function to update window borders after overwriting them with graphics. 
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SETTING UP A SUPERBITMAP WINDOW 

SuperBitMap windows are created by setting the WFLG_SUPERBITMAP flag, or by specifying the 
WASUPERBITMAP tag in the OpenWindowTagList() call. A pointer to an allocated and initialized BitMap 
structure must be provided. 

A SuperBitMap window requires the application to allocate and initialize its own bitmap. This entails allocating 
a BitMap structure, initializing the structure and allocating memory for the bit planes. 

Allocate a BitMap structure with the Exec AllocMem() function. Then use the graphics function InitBitMapQ 
to initialize the BitMap structure: 

void InitBitMap ( struct BitMap *bitMap, long depth, long width, long height ) ; 

InitBitMapQ fills in fields in the BitMap structure describing how a linear memory area is organized as a 
series of one or more rectangular bit-planes. 

Once you have allocated and initialized the BitMap structure, use the graphics library function AllocRasterQ 
to allocate the memory space for all the bit planes. 

PLANEPTR AllocRaster( unsigned long width, unsigned long height ) ; 

The example listed in the next section shows how to allocate a BitMap structure, initialize it with InitBitMapO 
and use AllocRaster() function to set up memory for the bitplanes. 

Graphics and Layers Functions for SuperBitMap Windows 

The portion of the bitmap showing within a SuperBitMap window is controlled by the application. Initially, the 
window shows the bitmap starting from its origin (0,0) and clipped to fit within the window layer. The visible 
portion of the bitmap can be scrolled around within the window using the layers library ScrollLayer() function: 

void ScrollLayer (LONG unused, struct Layer *layer, LONG dx, LONG dy) 

Pass this function a pointer to the window's layer in layer and the scroll offsets in dx and dy. (A pointer to the 
window's layer can be obtained from Window.RPort->Layer.) 

When rendering operations are performed in a SuperBitMap window, any rendering that fails outside window 
boundaries is done in the application's bitmap. Rendering that falls within window bounds is done in the 
screen's bitmap. Before performing an operation such as a save on the application bitmap, the graphics library 
function SyncSBitMap() should be called: 

void SyncSBltMap (struct Layer *layer) 

Pass this function a pointer to the window's layer. SyncSBitMap() copies the window contents to the 
corresponding part of the application bitmap, bringing it up to date. (If no rendering operations have been 
performed this call is not necessary.) 
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Similarly, after making any changes to the application bitmap such as loading a new one, the window's layer 
should be locked and the CopySBitMap() function should be called. 

void CopySBitMap (struct Layer *) 

This function copies the new information in the appropriate area of the underlying bitmap to the window's 
layer. 

For more information about bitmaps and layers, see the "Graphics Primitives" and "Layers Library" chapters of 
this manual. Also see the <graphics/clip.h>, <graphics/gfx.h>, <graphics/layers.h>, graphics library and layers 
library sections of the Amiga ROM Kernel Reference Manual: Includes and Autodocs. 

SuperBitMap Window Example 

This example shows how to implement a superbitmap, and uses a host of Intuition facilities. Further reading 
of other Intuition and graphics chapters may be required for a complete understanding of this example. 

;/* lines. c - Execute me to compile me with SAS C 5.10 

LC -bl -cfistq -v -y -j73 lines. c 

Blink FROM LIB:c.o, lines. o TO lines LIBRARY LIB : LC . lib, LIB : Amiga . lib 

quit 

** This example shows how to implement a superbitmap, and uses a host of 
** Intuition facilities. Further reading of other Intuition and graphics 
** chapters may be required for a complete understanding of this example. 
* * 

** lines. c -- implements a superbitmap with scroll gadgets 

** This program requires V37, as it uses calls to OpenWindowTags ( ) , 

** LockPubScreen ( ) . 

*/ 

/* Enforces use of new prefixed Intuition flag names */ 
#define INTUI_V3 6_NAMES_ONLY 

#include <exec/types . h> 
#include <exec/memory .h> 
#include <intuition/intuition.h> 

#include <clib/exec_protos . h> 
#include <clib/layers_protos .h> 
#include <clib/graphics_protos . h> 
#include <clib/intuition_protos .h> 

/* Random number function in amiga.lib (see amiga.lib.doc) */ 
UWORD RangeRand ( unsigned long maxValue ) ; 

#ifdef LATTICE 

int CXBRK(void) { return(O); } /* Disable Lattice CTRL/C handling */ 

int chkabort (void) { return(O); } /* really */ 

ttendif 

#define WIDTH_SUPER (800) 
#define HEIGHT_SUPER (600) 

#define UP_DOWN_GADGET (0) 
#define LEFT_RIGHT_GADGET (1) 
#define NO GADGET (2) 



#define MAXPROPVAL (OxFFFFL) 

#define GADGETID (x) (((struct Gadget * ) (msg- >IAddress) ) - >GadgetID) 

#define LAYERXOFFSET (x) (x- >RPort- >Layer- >Scroll_X) 
#define LAYERYOFFSET (x) (x->RPort->Layer->Scroll_Y) 

/* A string with this format will be found by the version command 

** supplied by Commodore. This will allow users to give version 

** numbers with error reports. 

*/ 

UBYTE vers [] = " $VER : lines 37.2"; 

struct Library *Gf xBase; 
struct Library *IntuitionBase; 
struct Library *LayersBase; 

struct Window *Win = NULL; /* window pointer */ 
struct Proplnfo BotGadlnfo = {Ob- 
struct Image BotGadlmage = {o}; 
struct Gadget BotGad = {o}; 
struct Proplnfo SideGadlnfo = {o}; 
struct Image SideGadlmage = {o}; 
struct Gadget SideGad = {o}; 

/* Prototypes for our functions */ 

VOID initBorderProps (struct Screen *myscreen) ; 

VOID doNewSize (void) ; 

VOID doDrawStuf f (void) ; 

VOID doMsgLoop (void) ; 

VOID superWindow (struct Screen *myscreen) ; 

/* 

** main 

** Open all required libraries and get a pointer to the default public screen. 

** Cleanup when done or on error. 

*/ 

VOID main(int argc, char **argv) 

{ 

struct Screen *myscreen; 

/* open all of the required libraries for the program. 
* * 

** require version 37 of the Intuition library. 

*/ 

if (IntuitionBase = OpenLibrary ( "intuition. library" , 37L) ) 

{ 

if (Gf xBase = OpenLibrary ( "graphics . library" , 33L) ) 

{ 

if (LayersBase = OpenLibrary ( "layers . library" , 33L) ) 

{ 

/* LockPubScreen ( ) /UnlockPubScreen is only available under V36 

** and later... Use GetScreenData ( ) under V34 systems to get a 

** copy of the screen structure. . . 

*/ 

if (NULL != (myscreen = LockPubScreen (NULL) ) ) 

{ 

superWindow (myscreen) ; 

UnlockPubScreen (NULL , myscreen) ; 

} 
CloseLibrary (LayersBase) ; 



} 

CloseLibrary (GfxBase) ; 

} 
CloseLibrary (IntuitionBase) ; 

} 
} 

/* 

** Create, initialize and process the super bitmap window. 

** Cleanup if any error. 

*/ 

VOID superWindow (struct Screen *myscreen) 

{ 

struct BitMap *bigBitMap; 

WORD planeNum; 

WORD allocatedBitMaps; 

/* set-up the border prop gadgets for the OpenWindow ( ) call. */ 
initBorderProps (myscreen) ; 

/* The code relies on the allocation of the BitMap structure with 

** the MEMF_CLEAR flag. This allows the assumption that all of the 

** bitmap pointers are NULL, except those successfully allocated 

** by the program. 

*/ 

if (bigBitMap = AllocMem (sizeof (struct BitMap), MEMF_PUBLIC | MEMF_CLEAR) ) 

{ " 

InitBitMap (bigBitMap, myscreen- >BitMap .Depth, WIDTH_SUPER, HEIGHT_SUPER) ; 

allocatedBitMaps = TRUE; 
for (planeNum = ; 

(planeNum < myscreen- >BitMap. Depth) && (allocatedBitMaps == TRUE); 
planeNum++) 

{ 

bigBitMap- >Planes [planeNum] = AllocRaster (WIDTH_SUPER, HEIGHT_SUPER) ; 

if (NULL == bigBitMap- >Planes [planeNum] ) 

allocatedBitMaps = FALSE; 
} 

/* Only open the window if the bitplanes were successfully 

** allocated. Fail silently if they were not. 

*/ 

if (TRUE == allocatedBitMaps) 

{ 

/* OpenWindowTags ( ) and OpenWindowTagList ( ) are only available 

** when the library version is at least V36. Under earlier 

** versions of Intuition, use OpenWindow ( ) with a NewWindow 

** structure. 

*/ 

if (NULL != (Win = OpenWindowTags (NULL, 

WA_Width, 15 0, 

WA_Height, 4 * (myscreen- >WBorTop + myscreen- >Font->ta_YSize ■ 



1) 



WA_MaxWidth, WIDTH_SUPER, 

WA_MaxHeight, HEIGHT_SUPER, 

WA_IDCMP, IDCMP_GADGETUP | IDCMP_GADGETDOWN | 

IDCMP_NEWSIZE | IDCMP_INTUITICKS | IDCMP_CLOSEWINDOW, 

WA_Flags, WFLG_SIZEGADGET | WFLG_SIZEBRIGHT | WFLG_SIZEBBOTTOM | 
WFLG_DRAGBAR | WFLG_DEPTHGADGET | WFLG_CLOSEGADGET | 
WFLG_SUPER_BITMAP | WFLG_GIMMEZEROZERO | WFLG_NOCAREREFRESH, 

WA_Gadgets, &(SideGad), 

WA_Title, &vers [6] , /* take title from version string */ 



} 



WA_PubScreen, myscreen, 
WA_SuperBitMap, bigBitMap, 
TAG_DONE) ) ) 

{ 

/* set-up the window display */ 

SetRast (Win->RPort, 0) ; /* clear the bitplanes */ 

SetDrMd(Win->RPort, JAM1) ; 

doNewSize ( ) ; /* adjust props to represent portion visible */ 
doDrawStuf f () ; 

/* process the window, return on IDCMP_CLOSEWINDOW */ 
doMsgLoop ( ) ; 

CloseWindow (Win) ; 



for (planeNum = 0; planeNum < myscreen- >BitMap .Depth; planeNum++) 

{ 

/* free only the bitplanes actually allocated. . . */ 

if (NULL != bigBitMap- >Planes [planeNum] ) 

FreeRaster (bigBitMap- >Planes [planeNum] , WIDTH_SUPER, HEIGHT_SUPER) ; 

} 
FreeMem (bigBitMap, sizeof (struct BitMap) ) ; 

} 



/* 

** Set-up the prop gadgets- -initialize them to values that fit 
** into the window border. The height of the prop gadget on the side 
** of the window takes the height of the title bar into account in its 
** set-up. note the initialization assumes a fixed size "sizing" gadget. 

* * 

** Note also, that the size of the sizing gadget is dependent on the 
** screen resolution. The numbers given here are only valid if the 
** screen is NOT lo-res. These values must be re-worked slightly 
** for lo-res screens. 

* * 

** The PROPNEWLOOK flag is ignored by 1.3. 

*/ 

VOID initBorderProps (struct Screen *myscreen) 

{ 

/* initializes the two prop gadgets. 

* * 

** Note where the PROPNEWLOOK flag goes. Adding this flag requires 

** no extra storage, but tells the system that our program is 

** expecting the new-look prop gadgets under 2.0. 

*/ 

BotGadlnfo. Flags = AUTOKNOB | FREEHORIZ | PROPNEWLOOK; 

BotGadlnfo.HorizPot = ; 

BotGadlnfo. VertPot = 0; 

BotGadlnfo .HorizBody = -1; 

BotGadlnfo. VertBody = -1; 

BotGad.LeftEdge = 3; 

BotGad.TopEdge = -7; 

BotGad. Width = -23; 

BotGad. Height = 6; 

BotGad. Flags = GFLG_RELBOTTOM | GFLG_RELWIDTH; 

BotGad. Activation = GACT RELVERIFY GACT IMMEDIATE I GACT BOTTOMBORDER; 



BotGad . GadgetType 
BotGad . GadgetRender 
BotGad . Speciallnf o 
BotGad. GadgetID 



GTYP_PROPGADGET | GTYP_GZZGADGET; 

(APTR) &(BotGadImage) ; 
(APTR) & (BotGadlnfo) ; 
LEFT RIGHT GADGET; 



SideGadlnfo. Flags = AUTOKNOB 
SideGadlnfo.HorizPot = 0; 
SideGadlnfo. VertPot = ; 
SideGadlnfo. HorizBody = -1; 
SideGadlnfo. VertBody = -1; 



FREEVERT PROPNEWLOOK; 



/* NOTE the TopEdge adjustment for the border and the font for V36. 
*/ 



SideGad.LeftEdge 
SideGad . TopEdge 
SideGad. Width 
SideGad. Height 



-14; 

myscreen->WBorTop + myscreen->Font->ta_YSize + 2; 

12; 

-SideGad. TopEdge - 11; 



SideGad. Flags 
SideGad. Activation 
SideGad . GadgetType 
SideGad . GadgetRender 
SideGad. Speciallnf o 
SideGad. GadgetID 
SideGad. NextGadget 
} 



GFLG_RELRIGHT | GFLG_RELHEIGHT ; 
GACT_RELVERIFY | GACT_IMMEDIATE | 
GTYP_PROPGADGET | GTYP_GZZGADGET; 

(APTR) & (SideGadlmage) ; 

(APTR) & (SideGadlnfo) ; 
UP_DOWN_GADGET ; 
& (BotGad) ; 



GACT RIGHTBORDER; 



/* 

** This function does all the work of drawing the lines 

*/ 

VOID doDrawStuff () 

{ 

WORD xl , yl , x2 , y2 ; 

WORD pen, ncolors, deltx, deity; 

ncolors = 1 << Win- >WScreen->BitMap. Depth; 
deltx = RangeRand (6) +2 ; 
deity = RangeRand (6) +2 ; 

pen = RangeRand (ncolors-1) + 1; 
SetAPen(Win->RPort,pen) ; 

for(xl=0, yl=0, x2=WIDTH_SUPER-l, y2=HEIGHT_SUPER-l ; 
xl < WIDTH_SUPER; 

xl += deltx, x2 -= deltx) 

{ 

Move (Win- >RPort , xl , yl ) ; 

Draw (Win- >RPort , x2 , y2 ) ; 

} 

pen = RangeRand (ncolors-1) + 1; 
SetAPen(Win->RPort,pen) ; 

for(xl=0, yl=0, x2=WIDTH_SUPER-l, y2=HEIGHT_SUPER-l ; 
yl < HEIGHT_SUPER; 

yl += deity, y2 -= deity) 

{ 

Move (Win- >RPort , xl , yl ) ; 

Draw (Win- >RPort , x2 , y2 ) ; 

} 



/* 

** This function provides a simple interface to ScrollLayer 



*/ 

VOID slideBitMap (WORD Dx,WORD Dy) 

{ 

ScrollLayer ( , Win- >RPort- >Layer , Dx, Dy) ; 

} 

/* 

** Update the prop gadgets and bitmap positioning when the size changes. 

*/ 

VOID doNewSize () 

{ 

ULONG tmp; 

tmp = LAYERXOFFSET(Win) + Win- >GZZWidth; 
if (tmp >= WIDTH_SUPER) 

slideBitMap (WIDTH_SUPER-tmp, 0) ; 

NewModifyProp(&(BotGad) , Win, NULL, AUTO KNOB | FREEHORIZ, 
( (LAYERXOFFSET(Win) * MAXPROPVAL) / 
(WIDTH_SUPER - Win->GZZWidth) ) , 
NULL, 

( (Win->GZZWidth * MAXPROPVAL) / WIDTH_SUPER) , 
MAXPROPVAL , 
1) ; 

tmp = LAYERYOFFSET(Win) + Win- >GZZHeight ; 
if (tmp >= HEIGHT_SUPER) 

slideBitMap (0, HEIGHT_SUPER- tmp) ; 

NewModifyProp(&(SideGad) , Win, NULL, AUTOKNOB | FREEVERT, 
NULL, 
( (LAYERYOFFSET(Win) * MAXPROPVAL) / 

(HEIGHT_SUPER - Win- >GZZHeight ) ) , 
MAXPROPVAL, 

( (Win->GZZHeight * MAXPROPVAL) / HEIGHT_SUPER) , 
1) ; 
} 

/* 

** Process the currently selected gadget. 

** This is called from IDCMP_INTUITICKS and when the gadget is released 

** IDCMP_GADGETUP . 

*/ 

VOID checkGadget (UWORD gadgetID) 

{ 

ULONG tmp; 
WORD dX = 0; 
WORD dY = 0; 

switch (gadgetID) 

{ 

case UP_DOWN_GADGET : 

tmp = HEIGHT_SUPER - Win- >GZZHeight ; 

tmp = tmp * SideGadlnf o.VertPot ; 

tmp = tmp / MAXPROPVAL; 

dY = tmp - LAYERYOFFSET (Win) ; 

break; 
case LEFT_RIGHT_GADGET : 

tmp = WIDTH_SUPER - Win- >GZZWidth; 

tmp = tmp * BotGadlnfo .HorizPot ; 

tmp = tmp / MAXPROPVAL; 

dX = tmp - LAYERXOFFSET(Win) ; 



break; 

} 
if (dX | | dY) 

slideBitMap(dX,dY) ; 
} 

/* 

** Main message loop for the window. 

*/ 

VOID doMsgLoop ( ) 

{ 

struct IntuiMessage *msg; 

WORD flag = TRUE; 

UWORD currentGadget = NO_GADGET; 

while (flag) 

{ 

/* Whenever you want to wait on just one message port */ 

/* you can use WaitPort ( ) . WaitPort ( ) doesn't require */ 

/* the setting of a signal bit. The only argument it */ 

/* requires is the pointer to the window's UserPort */ 

WaitPort (Win- >UserPort) ; 

while (msg = (struct IntuiMessage *) GetMsg (Win->UserPort) ) 

{ 

switch (msg->Class) 

{ 

case IDCMP_CLOSEWINDOW: 

flag = FALSE; 

break; 
case IDCMP_NEWSIZE: 

doNewSize ( ) ; 
doDrawStuf f () ; 

break; 
case IDCMPJ3ADGETD0WN: 

currentGadget = GADGETID (msg) ; 

break; 
case IDCMP_GADGETUP ; 

checkGadget (currentGadget) ; 

currentGadget = N0J3ADGET; 

break; 
case IDCMP_INTUITICKS: 

checkGadget (currentGadget) ; 

break; 

} 
ReplyMsg ( (struct Message *)msg); 

} 

} 
} 

The Window Structure 

The Window structure is the main Intuition data structure used to represent a window. For the most part, 
applications treat this structure only as a handle. Window operations are performed by calling system 
functions that take Window as an argument instead of directly manipulating fields within the structure. 
However, there are some useful variables in a Window structure which are discussed in this section. 

struct Window 

{ 

struct Window *NextWindow; 

WORD LeftEdge, TopEdge , Width, Height; 



}; 



WORD MouseY, MouseX; 

WORD MinWidth, MinHeight; 

UWORD MaxWidth, MaxHeight; 

ULONG Flags; 

struct Menu *MenuStrip; 

UBYTE *Title; 

struct Requester *FirstRequest , *DMRequest; 

WORD ReqCount; 

struct Screen *WScreen; 

struct RastPort *RPort; 

BYTE BorderLeft, BorderTop, BorderRight, BorderBottom; 

struct EastPort *BorderRPort ; 

struct Gadget *FirstGadget ; 

struct Window * Parent, *Descendant; 
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UWORD * Pointer; 

BYTE PtrHeight, PtrWidth; 

BYTE XOffset, YOffset; 

ULONG IDCMPFlagS; 

struct MsgPort *UserPort, *WindowPort ; 

struct IntuiMessage *MessageKey; 

UBYTE DetailPen, BlockPen; 

struct Image *CheckMark; 

UBYTE *ScreenTitle; 

WORD GZZMouseX, GZZMouseY, GZZWidth, GZZHeight; 

UBYTE *ExtData; 

BYTE *UserData; 

struct Layer *WLayer; 

struct TextFont *IFont; 

ULONG MoreFlags; 



LeftEdge, TopEdge, Width and Height 

These variables reflect current position and size of the window. If the user sizes or positions the window, 
then these values will change. The position of the window is relative to the upper left corner of the screen. 

MouseX, MouseY, GZZMouseX, GZZMouseY 

The current position of the Intuition pointer with respect to the window, whether or not this window is 
currently the active one. For GimmeZeroZero windows, the GZZ variables reflect the position relative to 
the inner layer (see "Window Types" below). For normal windows, the GZZ variables reflect the position 
relative to the window origin after taking the borders into account. 

ReqCount 

Contains a count of the number of requesters currently displayed in the window. Do not rely on the value 
in this field, instead use IDCMP_REQSET and IDCMP_REQCLEAR to indirectly determine the number of 
open requesters in the window. 

WScreen 

A pointer to the Screen structure of the screen on which this window was opened. 

RPort 

A pointer to this window's RastPort structure. Use this RastPort pointer to render into your window with 
Intuition or graphics library rendering functions. 

BorderLeft, BorderTop, BorderRight, BorderBottom 

These variables describe the actual size of the window borders. The border size is not changed after the 
window is opened. 

BorderRPort 



With GimmeZeroZero windows, this variable points to the RastPort for the outer layer, in which the 
border gadgets are kept. 

UserData 

This pointer is available for application use. The program can attach a data block to this window by setting 
this variable to point to the data. 

For a commented listing of the Window structure see <intuition/intuition.h> in the Amiga ROM Kernel 
Reference Manual: Includes and Autodocs. 
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Window Attributes 



This section discusses all window attributes. As mentioned earlier, a window's attributes may be specified with 
either Tagltems, NewWindow or ExtNewWindow depending on how the window is opened. 

Attributes are listed here by their Tagltem ID name (Tagltem.ti_Tag). For each tag item, the equivalent field 
setting in the NewWindow structure is also listed if it exists. Some window attributes specified with tags are 
available only in Release 2 and have no NewWindow equivalent. 



EXTENDED NEW WINDOW 

Of the three functions for opening a window, only OpenWindow() is present in all versions of the OS. This 
function takes a NewWindow structure as its sole argument. In order to allow applications to use the 
OpenWindow() call with Release 2 Tagltem attributes, an extended version of the NewWindow structure has 
been created named ExtNewWindow. 

Setting WFLG_NW_EXTENDED in the NewWindow. Flags field specifies to the OpenWindow() call that this 
NewWindow structure is really an ExtNewWindow structure. This is simply a standard NewWindow 
structure with a pointer to a tag list at the end. Since WFLG_NW_EXTENDED is ignored prior to V36, 
information provided in the tag list will be ignored by earlier versions of Intuition. Note that 
WFLG_NW_EXTENDED may not be specified in the WA_Flags tag. 

WINDOW ATTRIBUTE TAGS 

WA_Left, WA_Top, WA_Width and WA_Height 

Describe where the window will first appear on the screen and how large it will be initially. These 
dimensions are relative to the top left corner of the screen, which has the coordinates (0,0). 

WA_Left is the initial x position, or offset, from the left edge of the screen. The leftmost pixel is pixel 0, 
and values increase to the right. Equivalent to NewWindow. LeftEdge. 

WA_Top is the initial y position, or offset, from the top edge of the screen. The topmost pixel is pixel 0, 
and values increase to the bottom. Equivalent to NewWindow.TopEdge. 

WA_Width is the initial window width in pixels. Equivalent to NewWindow.Width. 

WA_Height is the initial window height in lines. Equivalent to NewWindow.Height. 

WA Detail Pen and WA BlockPen 

WA_DetailPen specifies the pen number for the rendering of window details like gadgets or text in the 
title bar. WA_BlockPen specifies the pen number for window block fills, like the title bar. These pens are 
also used for rendering menus. Equivalent to NewWindow. DetailPen and NewWindow. BlockPen. 

The specific color associated with each pen number depends on the screen. Specifying -1 for these 



values sets the window's detail and block pen the same as the screen's detail and block pen. 

Detail pen and block pen have largely been replaced starting with V36 by the pen array in the Drawlnfo 
structure. See the section on "Drawlnfo and the 3D Look" in the "Intuition Screens" chapter for more 
information. 
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WAJDCMP 

IDCMP flags tell Intuition what user input events the application wants to be notified about. The IDCMP 
flags are listed and described in the OpenWindowTagList() description in the Amiga ROM Kernel 
Reference Manual: Includes and Autodocs and in the chapter "Intuition Input and Output Methods" in this 
book. Equivalent to NewWindow. IDCMPFiags. 

If any of these flags are set, Intuition creates a pair of message ports for the window (one internal to 
Intuition and one used by the application). These ports are for handling messages about user input 
events. If WAJDCMP is NULL or unspecified, no IDCMP is created for this window. 

The ModifylDCMP() function can be used to change the window's IDCMP flags after it is open. 

WA_Gadgets 

A pointer to the first in the linked list of Gadget structures that are to be included in this window. These 
gadgets are application gadgets, not system gadgets. See the "Intuition Gadgets" chapter for more 
information. Equivalent to NewWindow. FirstGadget. 

WA_Checkmark 

A pointer to an Image structure, which is to be used as the checkmark image in this window's menus. To 
use the default checkmark, do not specify this tag or set this field to NULL. Equivalent to 
NewWindow.CheckMark. 

WA_Title 

A pointer to a NULL terminated text string, which is used as the window title and is displayed in the 
window's title bar. 

Intuition draws the text using the colors defined in the Drawlnfo pen array (Drawlnfo. driPens) and 
displays as much as possible of the window title, depending upon the current width of the title bar. 
Equivalent to NewWindow.Title. See the section on "Drawlnfo and the 3D Look" in the "Intuition Screens" 
chapter for more information on the pen array. 

The title is rendered in the screen's default font. 

A title bar is added to the window if any of the properties WA_DragBar (WFLG_WINDOWDRAG), 
WA_DepthGadget (WFLG_WINDOWDEPTH), WA_CloseGadget (WFLG_WINDOWCLOSE) or 
WA_Zoom are specified, or if text is specified for a window title. If no text is provided for the rifle, but one 
or more of these system gadgets are specified, the title bar will be blank. Equivalent to 
NewWindow.Title. 

WA_ScreenTitle 

A pointer to a NULL terminated text string, which is used as the screen title and is displayed, when the 
window is active, in the screen's title bar. After the screen has been opened the screen's title may be 
changed by calling SetWindowTitles() (which is the only method of setting the window's screen title prior 
toV36). 

WA_CustomScreen 

A pointer to the Screen structure of a screen created by this application. The window will be opened on 
this screen. The custom screen must already be opened when the OpenWindowTagList() call is made. 
Equivalent to NewWindow. Screen, also implies NewWindow.Type of CUSTOMSCREEN. 
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These tags set the minimum and maximum values to which the user may size the window. If the flag 
WFLG_WINDOWSIZING is not set, then these variables are ignored. Values are measured in pixels. Use 
(~0) for the WA_MaxWidth (WA_MaxHeight) to allow for a window as wide (tall) as the screen. This is the 
complete screen, not the visible part or display clip. 

Setting any of these variables to 0, will take the setting for that dimension from its initial value. For 
example, setting MinWidth to 0, will make the minimum width of this window equal to the initial width of 
the window. 

Equivalent to NewWindow. MinWidth, NewWindow.MinHeight, NewWindow.MaxWidth and 
NewWindow.MaxHeight. Use the WindowLimits() function to change window size limits after the 
window is opened. 

WA InnerWidth and WA InnerHeight 

Specify the dimensions of the interior region of the window, i.e., inside the border, independent of the 
border widths. When using WAJnnerWidth and WAJnnerHeight an application will probably want to set 
WAAutoAdjust (see below). 

WA_PubScreen 

Open the window as a visitor window on the public screen whose address is in the ti_Data field of the 
WA_PubScreen Tagltem. To ensure that this screen remains open until OpenWindowTagListQ has 
completed, the application must either be the screen's owner, have a window open on the screen, or use 
LockPubScreenO. Setting this tag implies screen type of PUBLICSCREEN. 

WAPubScreenName 

Declares that the window is to be opened as a visitor on the public screen whose name is pointed to by 
the ti_Data field of the WA_PubScreenName Tagltem. The OpenWindowTagList() call will fail if it 
cannot obtain a lock on the named public screen and no fall back name (WA_PubScreenFallBack) is 
specified. Setting this tag implies screen type of PUBLICSCREEN. 

WA_PubScreenFailBack 

A Boolean, specifies whether a visitor window should "fall back" to the default public screen (or 
Workbench) if the named public screen isn't available This tag is only meaningful when used in 
conjunction with WA_PubScreenName. 

WA_Zoom 

Pointer to an array of four WORDs, the initial LeftEdge, TopEdge, Width and Height values for the 
alternate zoom position and size. It also specifies that the application wants a zoom gadget for the 
window, whether or not it has a sizing gadget. 

A zoom gadget is always supplied to a window if it has both depth and sizing gadgets. This tag allows the 
application to open a window with a zoom gadget when the window does not have both the depth and 
sizing gadgets. 

WAMouseQueue 

An initial value for the mouse message backlog limit for this window. The SetMouseQueue() function will 
change this limit after the window is opened. 

WA_RptQueue 

An initial value of repeat key backlog limit for this window. 
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BOOLEAN WINDOW ATTRIBUTE TAGS 

These boolean window tags are alternatives to the NewWindow.Flags bit fields with similar names. Unlike 
the tags discussed above, the ti_Data field of these Tagltems is set to either TRUE or FALSE. 

WA_SizeGadget 

Specifying this flag tells Intuition to add a sizing gadget to the window. Intuition places the sizing gadget in 
the lower right corner of the window. By default, the right border is adjusted to accommodate the sizing 
gadget, but the application can specify one of the following two flags to change this behaviour. The 



WFLG_SIZEBRIGHT flag puts the sizing gadget in the right border. The WFLG_SIZEBBOTTOM flag puts 
the sizing gadget in the bottom border. Both flags may be specified, placing the gadget in both borders. 
Equivalent to NewWindow.Flags WFLG_SIZEGADGET. 

WA_SizeBRight 

Place the size gadget in the right border. Equivalent to NewWindow.Flags WFLG_SIZEBRIGHT. 

WA_SizeBBottom 

Place the size gadget in the bottom border. Equivalent to NewWindow.Flags WFLG_SIZEBBOTTOM. 

WA_DragBar 

This flag turns the entire title bar of the window into a drag gadget, allowing the user to position the 
window by clicking in the title bar and dragging the mouse. Equivalent to NewWindow.Flags 
WFLG_DRAGBAR. 

WA_DepthGadget 

Setting this flag adds a depth gadget to the window. This allows the user to change the window's depth 
arrangement with respect to other windows on the screen. Intuition places the depth gadget in the upper 
right corner of the window. Equivalent to NewWindow. Flags WFLG_DEPTHGADGET. 

WA_CloseGadget 

Setting this flag attaches a close gadget to the window. When the user selects this gadget, Intuition 
transmits a message to the application. It is up to the application to close the window with a 
CloseWindowQ call. Intuition places the close gadget in the upper left corner of the window. Equivalent 
to NewWindow.Flags WFLG_CLOSEGADGET. 

WA_ReportMouse 

Send mouse movement events to the window as x,y coordinates. Also see the description of the IDCMP 
flag IDCMP_MOUSEMOVE, in the chapter "Intuition Input and Output Methods." Equivalent to 
NewWindow.Flags WFLG_REPORTMOUSE. 

The WFLG_REPORTMOUSE flag in the Flags field of the Window structure may be modified on the fly 
by the program. Changing this flag must be done as an atomic operation. Most compilers generate atomic 
code for operations such as window->flags I =WFLG_REPORTMOUSE Or window- >flags &= 
~WFLG_REPORTMOUSE. If you are unsure of getting an atomic operation from your compiler, you may 
wish to do this operation in assembler, or bracket the code with a Forbid()/Permit() pair. 

The use of the ReportMouseQ function is strongly discouraged, due to historic confusion over the 
parameter ordering. 
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WA_NoCareRefresh 

This window does not want IDCMP_REFRESHWINDOW events. Set this flag to prevent the window from 
receiving refresh window messages. Equivalent to NewWindow.Flags WFLG_NOCAREREFRESH. 
Intuition will manage BeginRefresh() and EndRefresh() internally. 

WA Borderless 

Open a window with no borders rendered by Intuition. Equivalent to NewWindow.Flags 
WFLG_BORDERLESS. 

Use caution setting this flag, as it may cause visual confusion on the screen. Also, some borders may be 
rendered if any of the system gadgets are requested, if text is supplied for the window's rifle bar, or if any 
of application gadgets are in the borders. 

WA_Backdrop 

Make this window a Backdrop window. Equivalent to NewWindow.Flags WFLG_BACKDROP. 

WA_GimmeZeroZero 

Set this tag to create a GimmeZeroZero window. GimmeZeroZero windows have the window border and 
border gadgets rendered into an extra layer. This extra layer slows down window operations, thus it is 
recommended that applications only use GimmeZeroZero windows when they are required. For clipping 



graphics to the area within the borders of a window, see the discussion of "Regions" in the "Layers 
Library" chapter. Equivalent to NewWindow.Flags WFLG_GIMMEZEROZERO. 

WA_Activate 

Activate the window when it opens. Equivalent to NewWindow.Flags WFLG_ACTIVATE. Use this flag 
carefully, as it can change where the user's input is going. 

WA_RMBTrap 

Catch right mouse button events for application use. Set this flag to disable menu operations for the 
window. When set, right mouse button events will be received as IDCMP_MOUSEBUTTONS with the 
MENUUP and MENUDOWN qualifiers. Equivalent to NewWindow. Flags WFLG_RMBTRAP. 

The WFLG_RMBTRAP flag in the Window structure Flags field may be modified on the fly by the 
program. Changing this flag must be done as an atomic operation, as Intuition can pre-empt a multistep 
set or clear operation. An atomic operation can be done in assembler, using 68000 instructions that 
operate directly on memory. If you are unsure of generating such an instruction, place the operation within 
a Forbid()/Permit() pair. This will ensure proper operation by disabling multitasking while the flag is being 
changed. 

WA_SimpleRefresh 

The application program takes complete responsibility for updating the window. Only specify if TRUE. 
Equivalent to NewWindow.Flags WFLG_SIMPLEREFRESH. 

WA_SmartRefresh 

Intuition handles all window updating, except for parts of the window revealed when the window is sized 
larger. Only specify if TRUE. Equivalent to NewWindow. Flags WFLG_SMARTREFRESH. 

WA_SmartRefresh windows without a sizing gadget will never receive refresh events due to the user 
sizing the window. However, if the application sizes the window through a call like ChangeWindowBox(), 
ZipWindow() or SizeWindow(), a refresh event may be generated. Use WANoCareRefresh to disable 
refresh events. 
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WASuperBitMap 

This is a pointer to a BitMap structure for a SuperBitMap window. The application will be allocating and 
maintaining its own bitmap. Equivalent to NewWindow. BitMap. Setting this tag implies the 
WFLG_SUPERBITMAP property. 

For complete information about SuperBitMap, see "Setting Up a SuperBitMap Window" in this chapter. 

WAAutoAdjust 

Allow Intuition to change the window's position and dimensions in order to fit it on screen. The window's 
position is adjusted first, then the size. This property may be especially important when using 
WAJnnerWidth and WAJnnerHeight as border size depends on a user specified font. 

WA_MenuHelp (new for V37, ignored by V36) 

Enables IDCMP_MENUHELP: pressing Help during menus will return IDCMP_MENUHELP message. 
See the "Intuition Menus" chapter for more information. 

WA_Flags 

Multiple initialization of window flags, equivalent to NewWindow.Flags. Use the WFLG_ constants to 
initialize this field, multiple bits may be set by ORing the values together. 

WA_BackFill 

Allows you to specify a backfill hook for your window's layer. See the description of 
CreateUpFrontHookLayer() in the "Layers Library" chapter. Note that this tag is implemented in V37, 
contrary to what some versions of the include files may say. 



Other Window Functions 



This section contains a brief overview of other Intuition functions that affect windows. For a complete 
description of all Intuition functions, see the Amiga ROM Kernel Reference Manual: Includes and Autodocs. 

MENUS AND THE ACTIVE WINDOW 

Menus for the active window will be displayed when the user presses the menu button on the mouse. Menus 
may be disabled for the window by not providing a menu strip, or by clearing the menus with 
ClearMenuStrip(). Similarly, if the active window has WFLG_RMBTRAP set, the menu button will not bring up 
the menus. 

Two other functions, SetMenuStrip() and ResetMenuStripQ, are used to attach or update the menu strip for 
a window. 

void ClearMenuStrip ( struct Window *window ) ; 

BOOL SetMenuStrip ( struct Window *window, struct Menu *menu ); 

BOOL ResetMenuStrip ( struct Window *window, struct Menu *menu ) ; 

If SetMenuStrip() has been called for a window, ClearMenuStripQ must be called before closing the window. 
After ClearMenuStripQ has been called, the user can no longer access menus for this window. See the 
chapter "Intuition Menus," for complete information about setting up menus. 
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REQUESTERS IN THE WINDOW 

Requesters are temporary sub-windows, usually containing several gadgets, used to confirm actions, access 
files, or adjust the options of a command the user has just given. Request() creates and activates a requester 
in the window. EndRequest() removes the requester from the window. 

BOOL Request ( struct Requester 'requester, struct Window *window ) ; 
void EndRequest ( struct Requester 'requester, struct Window 'window ) ; 

For simple requesters in a format that matches system requesters, two new functions have been added to 
Release 2: 

LONG EasyRequestArgs ( struct Window 'window, struct EasyStruct 'easyStruct, 

ULONG 'idcmpPtr, APTR args ) ; 
LONG EasyRequest ( struct Window 'window, struct EasyStruct 'easyStruct, 

ULONG 'idcmpPtr, APTR argl, ... ) ; 

The EasyRequest() functions support requesters with one or more gadgets automatically providing a layout 
that is sensitive to the current font and screen resolution. See the chapter "Intuition Requesters and Alerts" for 
more information on using requester functions. 

PROGRAM CONTROL OF WINDOW ARRANGEMENT 

MoveWindowQ, SizeWindow(), WindowToFrontQ and WindowToBackQ allow the program to modify the 
size and placement of its windows. These calls are available in all versions of the operating system. 

MoveWindowlnFrontOf(), ChangeWindowBox() and ZipWindow() have been added in Release 2 to 
provide more flexible control over the size and placement of windows. 

All of these functions are asynchronous. The window will not be affected by them immediately, rather, Intuition 
will act on the request the next time it receives an input event. Currently this happens at a minimum rate of ten 
times per second, and a maximum of sixty times per second. There is no guarantee that the operation has 
taken place when the function returns. In some cases, there are IDCMP messages which will inform the 
application when the change has completed (for example, an IDCMP_NEWSIZE event indicates that a resize 



operation has completed). 

Use the MoveWindow() function to move a window to a new position in the screen. Use SizeWindowQ to 
change the size of the window: 

void MoveWindow ( struct Window *window, long dx, long dy ) ; 
void SizeWindow( struct Window *window, long dx, long dy ) ; 

Note that both MoveWindowQ and SizeWindow() take the amount of change in each axis (delta values 
instead of absolute coordinates). To specify the coordinates as absolute numbers, use ChangeWindowBox(). 
The SizeWindow() function will respect the window's maximum and minimum dimensions only if the window 
has a sizing gadget. 

A new function in Release 2, ChangeWindowBox(), allows an application to change the window size and 
position in a single call: 

void ChangeWindowBox ( struct Window *window, long left, long top, long width, 
long height ) ; 

Note that the position and size values are absolutes and not deltas. The window's maximum and minimum 
dimensions are always respected. 
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To depth arrange windows under program control, use WindowToFront() and WindowToBack(): 

void WindowToFront ( struct Window *window ) ; 
void WindowToBack ( struct Window *window ) ; 

WindowToFront() depth arranges a given window in front of all other windows on its screen. 
WindowToBack() depth arranges a given window behind all other windows on its screen. 

To move a window in front of a specific, given window (as opposed to all windows), use 
MoveWindowlnFrontOf(): 

void MoveWindowlnFrontOf ( struct Window *window, struct Window *behindWindow ) ; 

MoveWindowlnFrontOf() is a new call provided in Release 2 and is not available in older versions of the OS. 

To toggle the window size between its two zoom settings use ZipWindow(). This performs the same action 
that occurs when the user selects the zoom gadget: 

void ZipWindow( struct Window *window ) ; 

The two zoom settings are the initial size and position of the window when it was first opened and the 
alternate position specified with the WA_Zoom tag. If no WA_Zoom tag is provided, the alternate position is 
taken from the window's minimum dimensions, unless the window was opened at its minimum dimension. In 
that ease, the alternate position is taken from the window's maximum dimension. ZipWindow() is a new call 
provided in Release 2 and is not available in older versions of the OS. 

CHANGING THE WINDOW OR SCREEN TITLE 

Each window has its own window tide and local screen tide. The window title, if specified, is always displayed 
in the window. The local screen tide, if specified, is only displayed in the screen's tide bar when the window is 
active. If the window does not specify a local screen tide, then the default screen tide is used in the screen title 
bar when this window is active. 

void SetWindowTitles ( struct Window *window, UBYTE *windowTitle, UBYTE 
*screenTitle ) ; 

This function changes the window tide or local screen tide for the given window. Both windowTitle and 



screenTitle can be set to -1 , NULL or a NULL terminated string. Specifying -1 will not change the tide from 
the current value. Specifying NULL will clear the window tide or reset the screen tide to the default title for the 
screen. 

CHANGING MESSAGE QUEUE LIMITS 

Starting with V36, windows have limits on the number of mouse movement and repeat key messages that 
may be waiting at their IDCMP at any time. These queue limits prevent the accumulation of these messages, 
which may arrive at the IDCMP message port in large numbers. 

Once a queue limit is reached, further messages of that type will be discarded by Intuition. The application will 
never hear about the discarded messages; they are gone forever. (Note that only mouse move and key repeat 
messages are limited this way. Other types of messages will still be added to the port.) Messages of the 
limited type will arrive at the port again after the application has replied to one of the messages in the queue. 
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The queue limits are independent of each other. Having reached the limit for one type of message does not 
prevent other types of messages (that have not yet reached their queuing limits) from being added to the 
IDCMP. Note that the queues apply only to the IDCMP and not to messages received directly via an input 
handler or from the console device. 

Order of event arrival is not a factor in the message count. Messages may be sequential or interspersed with 
other events-only the number of messages of the specific type waiting at the IDCMP matters. 

The WA_RptQueue tag allows setting an initial value for the repeat key backlog limit for the window. There is 
no function to change this value as of V37. The default value for WA_RptQueue is 3. 

The WA_MouseQueue tag allows setting an initial value for the mouse message backlog limit for the window. 
The default value for WA_MouseQueue is 5. The number may later be changed with a call to 
SetMouseQueue(): 

LONG SetMouseQueue{ struct Window *window, unsigned long queueLength ); 

Note that real information may be lost if the queue fills and Intuition is forced to discard messages. See the 
chapter "Intuition Mouse and Keyboard" for more information. 

CHANGING POINTER POSITION REPORTS 

Pointer position messages to a window may be turned on and off by simply setting or clearing the 
WFLG_REPORTMOUSE flag bit in Window->Flags, in an atomic way, as explained for the WA_RMBTrap 
tag in the "Window Attributes" section above. Using this direct method of setting the flag avoids the historic 
confusion on the ordering of the arguments of the ReportMouseQ function call. 

Mouse reporting may be turned on even if mouse movements were not activated when the window was 
opened. The proper IDCMP flags must be set for the window to receive the messages. See the chapter 
"Intuition Mouse and Keyboard" for more details on enabling mouse reporting in an application. 

CUSTOM POINTERS 

The active window also has control over the pointer. If the active window changes the image for the pointer 
using the functions SetPointer() or ClearPointerQ, the pointer image will change: 

void SetPointer ( struct Window *window, UWORD *pointer, long height, long width, 
long xOffset, long yOffset ) ; 

void ClearPointer ( struct Window *window ) ; 

SetPointer() sets up the window with a sprite definition for a custom pointer. If the window is active, the 
change takes place immediately. The pointer will not change if an inactive window calls SetPointer(). In this 



way, each window may have its own custom pointer that is displayed only when the window is active. 

ClearPointerQ clears the custom pointer from the window and restores it to the default Intuition pointer, which 
is set by the user. Setting a pointer for a window is discussed further in the chapter "Intuition Mouse and 
Keyboard' '. 
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Function Reference 



The following are brief descriptions of the Intuition functions that relate to the use of Intuition windows. See the 
Amiga ROM Kernel Reference Manual: Includes and Autodocs for details on each function call. 

Table 4-2: Functions for Intuition Windows 

Function Description 

OpenWindowTagListQ Open a window. 

OpenWindowTags() Alternate calling sequence for OpenWindowTagList(). 

OpenWindow() Pre-V36 way to open a window. 

CloseWindow() Close a window. 

BeginRefresh() Turn on optimized window refresh mode. 

EndRefresh() Turn off optimized window refresh mode. 

RefreshWindowFrame() Redraw the borders and border gadgets of an open window. 

ActivateWindow() Make an open window active. 

SizeWindow() Change the size of an open window. 

MoveWindow() Change the position of an open window. 

ChangeWindowBox() Change the size and position of an open window. 

WindowLimits() Change the minimum and maximum sizes of an open window. 

WindowToBack() Move a window behind all other windows. 

WindowToFront() Move a window in front of all other windows. 

MoveWindowlnFrontOf() Move a window in front of another window. 

ZipWindow() Change the size of window to its alternate size. 

SetWindowTitles() Change the window tides for the window and the screen. 

SetPointer() Set up a custom pointer to display whenever the window is active. 

ClearPointer() Restore the mouse pointer to its default imagery. 
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Chapter 5 

INTUITION GADGETS 

This chapter describes the multi-purpose software controls called gadgets. Gadgets are software controls 
symbolized by an image that the user can operate with the mouse or keyboard. They are the Amiga's 
equivalent of buttons, knobs and dials. 

Much of the user's input to an application takes place through gadgets in the application's windows and 
requesters. Gadgets are also used by Intuition itself for handling screen and window movement and depth 
arrangement, as well as window sizing and closing. 

Intuition maintains gadget imagery, watches for activation and deactivation and performs other management 
required by the gadget. The application can choose its level of involvement from simply receiving gadget 
activation messages to processing the actual mouse button presses and movements. To make gadget 
programming even easier, Release 2 of the Amiga operating system includes the new GadTools library. 
Applications written for Release 2 should take advantage of this new library (described separately in the 
"GadTools Library" chapter). 

About Gadgets 

There arc two kinds of gadgets: system gadgets and application gadgets. System gadgets arc set up by 
Intuition to handle the positioning and depth arranging of screens, and to handle the positioning, sizing, 
closing and depth arranging of windows. System gadgets always use the same imagery and location giving 
the windows and screens of any application a basic set of controls that are familiar and easy to operate. In 
general, applications do not have to do any processing for system gadgets; Intuition does all the work. 

Application gadgets are set up by an application program. These may be the basic gadget types described in 
this chapter, the pre-fabricated gadgets supplied by the GadTools library, or special gadget types defined 
through Intuition's custom gadget and BOOPSI facilities. Application gadgets can be placed anywhere within a 
window and can use just about any image. The action associated with an application gadget is carried out by 
the application. 
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There are four basic types of application gadgets: 

Boolean (or button) gadgets elicit true/false or yes/no kinds of answers from the user. 

Proportional gadgets allow the user to select from a continuous range of options, such as 
volume or speed. 

String gadgets are used to get or display character based information (a special class of string 
gadget allows entry of numeric data.) 

Custom gadgets, a new, generalized form of gadget, provide flexibility to perform any type of 
function. 

The way a gadget is used varies according to the type of gadget. For a boolean gadget, the user operates the 
gadget by simply clicking the mouse select button. For a string gadget, a cursor appears, allowing the user to 
enter data from the keyboard. For a proportional gadget, the user can either drag the knob with the mouse or 
click in the gadget container to move the knob by a set increment. 

Gadgets are chosen by positioning the pointer within an area called the select box, which is application 
defined, and pressing the mouse select button (left mouse button). 

When a gadget is selected, its imagery is changed to indicate that it is activated. The highlighting method for 



the gadget may be set by the application. Highlighting methods include alternate image, alternate border, a 
box around the gadget and color complementing. 

A gadget can be either enabled or disabled. Disabled gadgets cannot be operated and are indicated by 
ghosting the gadget, that is, overlaying its image with a pattern of dots. Gadgets may also be directly modified 
and redrawn by first removing the gadget from the system. 
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Drag Bar 



Zoom Gadget 



Button Gadget 




Depth Gadget 



\' Proportional Gadget 
Boolean Gadget 

Figure 5-1: System and Application Gadgets 
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SYSTEM GADGETS 

System gadgets are predefined gadgets provided by Intuition to support standard operations of windows and 
screens. System gadgets have a standard image and location in the borders of screens or windows. Intuition 
manages the operation of all system gadgets except the close gadget. 

The drag and depth gadgets are automatically attached to each screen in the system. The application cannot 
control the creation of these gadgets, but can control their display and operation. Screens may be opened 
"quiet", without any of the gadget imagery displayed. Applications should avoid covering the screen's gadgets 
with windows as this may prevent the user from freely positioning the screen. See the "Intuition Screens" 
chapter for more information on the positioning and use of system gadgets for screens. 

The drag, depth, close, sizing and zoom gadgets are available to be attached to each window. These gadgets 
are not provided automatically, the application must specify which gadgets it requires. See the "Intuition 
Windows" chapter for more information on the positioning and use of system gadgets for windows. 



APPLICATION GADGETS 



Application gadgets imitate real life controls: they are the switches, knobs, handles and buttons of the Intuition 
environment. Gadgets can be created with almost any imaginable type of imagery and function. Visual 
imagery for gadgets can combine text with hand drawn imagery or lines of multiple colors. 



A gadget is created by declaring and initializing a Gadget structure as defined in <intuition/intuition.h>. See 
the "Gadget Structure" section later in this chapter for more details. 

Gadgets always appear in a window or requester. All windows and requesters keep a list of the gadgets they 
contain. Gadgets can be added when the window or requester is opened, or they can be added or removed 
from the window or requester after it is open. 

As with other types of input events, Intuition notifies your application about gadget activity by sending a 
message to your window's I/O channels: the IDCMP (Window.UserPort) or the console device. The message 
is sent as an Intuition IntuiMessage structure. The Class field of this structure is set to 
IDCMP_GADGETDOWN or IDCMP_GADGETUP with the lAddress field set to the address of the Gadget 
that was activated. (See the chapter on "Intuition Input and Output Methods" for details.) 

Application gadgets can go anywhere in windows or requesters, including in the borders, and can be any size 
or shape. When application gadgets are placed into the window's border at the time the window is opened, 
Intuition will adjust the border size accordingly. Application gadgets are not supported in screens (although 
this may be simulated by placing the gadget in a backdrop window). 

Gadget size can be fixed, or can change relative to the window size. Gadget position can be set relative to 
either the top or bottom border, and either the left or fight border of the window, allowing the gadget to move 
with a border as the window is sized. 

This flexibility provides the application designer the freedom to create gadgets that mimic real devices, such 
as light switches or joysticks, as well as the freedom to create controls that satisfy the unique needs of the 
application. 
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A Simple Gadget Example 

The example below demonstrates a simple application gadget. The program declares a Gadget structure set 
up as a boolean gadget with complement mode highlighting. The gadget is attached to the window when it is 
opened by using the WAGadgets tag in the OpenWindowTags() call. 

;/* simplegad.c - Execute me to compile me with SAS C 5.10 

LC -bl -cfistq -v -y -J73 simplegad.c 

Blink FROM LIB: c.o, simplegad.o TO simplegad LIBRARY LIB : LC . lib, LIB : Amiga . lib 

quit 

** simplegad.c - show the use of a button gadget. 
*/ 

#define INTUI_V3 6_NAMES_ONLY 

#include <exec/types . h> 
#include <intuition/ intuition. h> 
#include <intuition/intuitionbase . h> 

#include <clib/execprotos .h> 
#include <clib/intuitionprotos . h> 

#include <stdio.h> 

#ifdef LATTICE 

int CXBRK(VOid) { return(O); } /* Disable Lattice CTRL/C handling */ 

int chkabort (void) { return(O) ; } /* really */ 

#endif 

struct Library *IntuitionBase; 



#define BUTTON_GAD_NUM (3) 
ttdefine MYBUTTONGADWIDTH (100) 
ttdefine MYBUTTONGADHEIGHT (50) 

/* NOTE that the use of constant size and positioning values are 

** not recommended; it Just makes it easy to show what is going on. 

** The position Of the gadget should be dynamically adjusted depending 

** on the height of the font in the title bar of the window. 

*/ 

UWORD buttonBorderData [] = 

{ 

0,0, MYBUTTONGADWIDTH + 1,0, MYBUTTONGADWIDTH + 1 , MYBUTTONGADHEIGHT + 1, 
0, MYBUTTONGADHEIGHT + 1, 0,0, 

}; 

struct Border buttonBorder = 

{ -1, -1,1,0, JAM1, 5, buttonBorderData, NULL, } ; 

struct Gadget buttonGad = 

{ 

NULL, 20,20, MYBUTTONGADWIDTH, MYBUTTONGADHEIGHT, 

GFLG_GADGHCOMP , GACT_RELVERIFY | GACT_IMMEDIATE, 

GTYP_BOOLGADGET , &bu{ tonBorder , NULL, NULL, 0,NULL, BUTTON_GAD_NUM , NULL, } ; 

/* 

** routine to show the use Of a button (boolean) gadget. 

*/ 

VOID main(int argc, char **argv) 

{ 

struct Window *win; struct IntuiMessage *msg; struct Gadget *gad; 
ULONG class; 
BOOL done; 

/* make sure to get intuition version 37, for OpenWindowTags ( ) */ 
IntuitionBase = OpenLibrary ( "intuition. library" , 37); 
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if (IntuitionBase) 

{ 

if (win = OpenWindowTags (NULL, 

WA_Width, 4 00, 

WA_Height, 10 0, 

WA_Gadgets, kbuttonGad, 

WA_Actlvate, TRUE, 

WA_CloseGadget, TRUE, 

WA_IDCMP, IDCMP_GADGETDOWN | IDCMP_GADGETUP | 

IDCMP_CLOSEWINDOW , 
TAG END) ) 

{ 

done = FALSE; 

while (done == FALSE) 

{ 

Wait(lL << win->UserPort->mp SigBit) ; 

while ( (done == FALSE) && (msg = (struct IntuiMessage 
*) GetMsg (win->UserPort) ) ) 

{ 

/* Stash message contents and reply, important when message 

** triggers some lengthy processing 

*/ 

class = msg->Class; 



/* gadget address is ONLY valid for gadget messages! */ 
if ( (class == IDCMP_GADGETUP) | | (class == IDCMP_GADGETDOWN) ) 
gad = (struct Gadget *) (msg->IAddress) ; 

ReplyMsg ( (struct Message *)msg); 

/* switch on the type of the event */ 
switch (class) 

{ 

case IDCMP_GADGETUP : 

/* caused by GACT_RELVERIFY */ 

printf (" received an IDCMP_GADGETUP , gadget 
number %d\n" , gad->GadgetID) ; 

break; 
case IDCMP_GADGETDOWN: 

/* caused by GACT_IMMEDIATE */ 

printf ( "received an IDCMP_GADGETDOWN, gadget 
number %d\n" , gad->GadgetID) ; 

break; 
case IDCMP_CLOSEWINDOW : 

/* set a flag that we are done processing 
events*/ 

printf ("received an IDCMP CLOSEWINDOW\n" ) ; 
done = TRUE; 
break; 
} 
} 
} 
CloseWindow (win) ; 

} 

CloseLibrary (IntuitionBase) ; 

} 

ADDING AND REMOVING GADGETS 

Gadgets may be added to a window or requester when the window or requester is opened, or they may be 
added later. To add the gadgets when a window is opened, use the WA_Gadgets tag with the 
OpenWindowTagList() call. This technique is demonstrated in the example above. For a requester, set the 
ReqGadget field in the Requester structure to point to the first gadget in the list. 

To add or remove gadgets in a window or requester that is already open, use AddGList() or RemoveGList(). 
These functions operate on gadgets arranged in a list. A gadget list is linked together by the NextGadget field 
of the Gadget structure (see the description of the Gadget structure later in this chapter). 
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AddGListQ adds a gadget list that you specify to the existing gadget list of a window or requester: 

UWORD AddGList ( struct Window *window, struct Gadget *agadget, 

unsigned long position, long numGad, struct Requester *requester) ; 

Up to numGad gadgets will be added from the gadget list you specify beginning with agadget. The position 
argument determines where your gadgets will be placed in the existing list of gadgets for the window or 
requester. Use (~0) to add your gadget list to the end of the window or requester's gadget list This function 
returns the actual position where your gadgets are added in the existing list. 

To remove gadgets from a window or requester use RemoveGList(): 

UWORD RemoveGList ( struct Window *remPtr, struct Gadget *agadget, long numGad ); 

This function removes up to numGad gadgets from a window or requester, beginning with the specified one. 
Starting with V37, if one of the gadgets that is being removed is the active gadget, this routine will wait for the 



user to release the mouse button before deactivating and removing the gadget. This function returns the 
former position of the removed gadget or -1 if the specified gadget was not found. 

The Gadget structure should never be directly modified after it has been added to a window or requester. To 
modify a gadget, first remove it with RemoveGList(), modify the structure as needed, and then add the gadget 
back to the system with AddGListQ. Finally, refresh the gadget imagery with RefreshGListQ. (See the 
section on "Gadget Refreshing" below for more information.) 

Some attributes of a gadget may be modified through special Intuition functions that perform the modification. 
When using such functions it is not necessary to remove, add or refresh the gadget. These functions, such as 
NewModifyProp(), OnGadget() and OffGadgetQ, are described later in this chapter. 



Gadget Imagery 



Gadget imagery can be rendered with a series of straight lines, a bitmap image or no imagery at all. In 
addition to the line or bitmap imagery, gadgets may include a series of text strings. 

HAND DRAWN GADGETS 

Bitmap or custom images are used as imagery for a gadget by setting the GFLG_GADGIMAGE flag in the 
Flags field of the Gadget structure. An Image structure must be set up to manage the bitmap data. The 
address of the image structure is placed into the gadget's GadgetRender field. The bitmap image will be 
positioned relative to the gadget's select box. For more information about creating Intuition images, see the 
chapter "Intuition Images, Line Drawing, and Text." For a listing of the Gadget structure and all its flags see 
the "Gadget Structure" section later in this chapter. 

LINE DRAWN GADGETS 

Gadget imagery can also be created by specifying a series of lines to be drawn. These lines can go around or 
through the select box of the gadget, and can be drawn using any color pen and draw mode. Multiple groups 
of lines may be specified, each with its own pen and draw mode. 
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The Border structure is used to describe the lines to be drawn. The Border structure is incorporated into the 
gadget by clearing the GFLG_GADGIMAGE flag in the gadget's Flags field. The address of the Border 
structure is placed into the gadget's GadgetRender field. The border imagery will be positioned relative to the 
gadget's select box. For more information about creating a Border structure, see the chapter "Intuition 
Images, Line Drawing, and Text." 

GADGET TEXT 

Gadgets may include text information in the form of a linked list of IntuiText structures. A pointer to the first 
IntuiText structure in the list is placed in the Gadget structure's GadgetText field. The text is positioned 
relative to the top left corner of the gadget's select box. For more information on IntuiText, see the "Intuition 
Images, Line Drawing and Text" chapter. 

GADGETS WITHOUT IMAGERY 

Gadgets can be created without any defining imagery. This type of gadget may be used where mouse 
information is required but graphical definition of the gadget is not, or where the existing graphics sufficiently 
define the gadget that no additional imagery is required. A gadget with no imagery may be created by clearing 
the GFLG_GADGIMAGE flag in the gadget's Flags field, and by setting the gadget's GadgetRender and 
GadgetText fields to NULL. 

The text display of a word processor is a case where mouse information is required without any additional 
graphics. If a large gadget is placed over the text display, gadget and mouse event messages may be 
received at the IDCMP (Window.UserPort) when the mouse select button is either pressed or released. The 
mouse information is used to position the pointer in the text, or to allow the user to mark blocks of text. The 



drag bar of a window is another example of a gadget where existing imagery defines the gadget such that 
additional graphics are not required. 



Gadget Selection 



The user operates a gadget by pressing the select button while the mouse pointer is within the gadget's select 
box. Intuition provides two ways of notifying your program about the user operating a gadget. If you application 
needs immediate notification when the gadget is chosen, set the GACTJMMEDIATE flag in the gadget's 
Activation field. Intuition will send an IDCMP_GADGETDOWN message to the window's UserPort when it 
detects the mouse select button being pressed on the gadget. 

If the application needs notification when the gadget is released, i.e., when the user releases the mouse select 
button, set the GACT_RELVERIFY (for "release verify") flag in the gadget's Activation field. For boolean 
gadgets, Intuition will send an IDCMP_GADGETUP message to the window's UserPort when the mouse 
select button is released over a GACT_RELVERIFY gadget. The program will only receive the 
IDCMP_GADGETUP message if the user still has the pointer positioned over the select box of the gadget 
when the mouse select button is released. 

If the user moves the mouse out of the gadget's select box before releasing the mouse button an 
IDCMP_MOUSEBUTTONS event will be sent with a code of SELECTUP. This indicates the user's desire not 
proceed with the action. Boolean gadgets that are GACT_RELVERIFY allow the user a chance to cancel a 
selection by rolling the mouse off of the gadget before releasing the select button. 
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String gadgets have a slightly different behaviour, in that they remain active after the mouse button has been 
released. The gadget remains active until Return or Enter is pressed, the user tabs to the next or previous 
gadget, another window becomes active or the user chooses another object with the mouse. An 
IDCMP_GADGETUP message is only sent for GACT_RELVERIFY string gadgets if the user ends the gadget 
interaction through the Return, Enter or (if activated) one of the tab keys. 

GACT_RELVERIFY proportional gadgets send IDCMP_GADGETUP events even if the mouse button is 
released when the pointer is not positioned over the select box of the gadget. 

Gadgets can specify both the GACTJMMEDIATE and GACT_RELVERIFY activation types, in which case, 
the program will receive both IDCMP_GADGETDOWN and IDCMP_GADGETUP messages. 



Gadget Size and Position 



The position and dimensions of the gadget's select box are defined in the Gadget structure. The LeftEdge, 
TopEdge, Width and Height values can be absolute numbers or values relative to the size of the window. 
When using absolute numbers, the values are set once, when the gadget is created. When using relative 
numbers, the size and position of the select box are adjusted dynamically every time the window size 
changes. 

The gadget image is positioned relative to the select box so when the select box moves the whole gadget 
moves. The size of the gadget image, however, is not usually affected by changes in the select box size 
(proportional gadgets are the exception). To create a gadget image that changes size when the select box and 
window change size, you have to handle gadget rendering yourself or use a BOOPSI gadget. 

SELECT BOX POSITION 

To specify relative position or size for the gadget's select box, set or more of the flags GFLG_RELRIGHT, 
GFLG_RELBOTTOM, GFLG_RELWIDTH or GFLG_RELHEIGHT in the Flags field of the Gadget structure. 
When using GFLG_RELxxx flags, the gadget size or position is recomputed each time the window is sized. 

Positioning the Select Box. With GFLG_RELxxx gadgets, all of the imagery must be 
contained within the gadget's select box. This allows Intuition to erase the gadget's 
imagery when the window is sized. Intuition must be able to erase the gadget's imagery 



since the gadget's position or size will change as the window size changes. If the old one 
were not removed, imagery from both sizes/positions would be visible. 

If a GFLG_RELxxx gadget's imagery must extend outside of its select box, position another 
GFLG_RELxxx gadget with a larger select box such that all of the first gadget's imagery is 
within the second gadget's select box. This "shadow" gadget is only used to clear the first 
gadget's imagery and, as such, it should not have imagery nor should it generate any 
messages. It should also be positioned later in the gadget list than the first gadget so that 
its select box does not interfere with the first gadget. 

The left-right position of the select box is defined by the variable LeftEdge, which is an offset from either the 
left or right edge of the display element. The offset method is determined by the GFLG_RELRIGHT flag. For 
the LeftEdge variable, positive values move toward the right and negative values move toward the left of the 
containing display element. If GFLG_RELRIGHT is cleared, LeftEdge is an offset (usually a positive value) 
from the left edge of the display element. 
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If GFLG_RELRIGHT is set, LeftEdge is an offset (usually a negative value) from the right edge of the display 
element. When this is set, the left-right position of the select box in the window is recomputed each time the 
window is sized. The gadget will automatically move with the left border as the window is sized. 

The top-bottom position of the select box is defined by the variable TopEdge, which is an offset from either 
the top or bottom edge of the display element (window or requester). The offset method is determined by the 
GFLG_RELBOTTOM flag. For the TopEdge variable, positive values move toward the bottom and negative 
values move toward the top of the containing display element. 

If GFLG_RELBOTTOM is cleared, TopEdge is an offset (usually a positive value) from the top of the display 
element. If GFLG_RELBOTTOM is set, TopEdge is an offset (usually a negative value) from the bottom of the 
display element. When this is set, the position of the select box is recomputed each time the window is sized. 
The gadget will automatically move with the bottom border as the window is sized. 

SELECT BOX DIMENSION 

The height and width of the gadget select box can be absolute or they can be relative to the height and width 
of the display element in which the gadget resides. 

Set the gadget's GFLG_RELWIDTH flag to make the gadget's width relative to the width of the window. When 
this flag is set, the Width value is added to the current window width to determine the width of the gadget 
select box. The Width value is usually negative in this case, making the width of the gadget smaller than the 
width of the window. If GFLG_RELWIDTH is not set, Width will specify the actual width of the select box. 

The actual width of the box will be recomputed each time the window is sized. Setting GFLG_RELWIDTH and 
a gadget width of zero will create a gadget that is always as wide as the window, regardless of how the 
window is sized. 

The GFLG_RELHEIGHT flag has the same effect on the height of the gadget select box. If the flag is set, the 
height of the select box will be relative to the height of the window, and the actual height will be recomputed 
each time the window is sized. If the flag is not set, the value will specify the actual height of the select box. 

Here are a few examples of gadgets that take advantage of the special relativity modes of the select box. 
Consider the Intuition window sizing gadget. The LeftEdge and TopEdge of this gadget are both defined 
relative to the right and bottom edges of the window. No matter how the window is sized, the gadget always 
appears in the lower right corner. 

For the window drag gadget, the LeftEdge and TopEdge are always absolute in relation to the top left corner 
of the window. Height of this gadget is always an absolute quantity. Width of the gadget, however, is defined 
to be zero. When Width is combined with the effect of the GFLG_RELWIDTH flag, the drag gadget is always 
as wide as the window. 

For a program with several requesters, each of which has an "OK" gadget in the lower left corner and a 



"Cancel" gadget in the lower right corner, two gadgets may be designed that will appear in the correct position 
regardless of the size of the requester. Design the "OK" and "Cancel" gadgets such that they are relative to 
the lower left and lower right corners of the requester. Regardless of the size of the requesters, these gadgets 
will appear in the correct position relative to these corners. Note that these gadgets may only be used in one 
window or requester at a time. 
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POSITIONING GADGETS IN WINDOW BORDERS 

Gadgets may be placed in the borders of a window. To do this, set one or more of the border flags in the 
Gadget structure and position the gadget in the window border. Setting these flags also tells Intuition to adjust 
the size of the window's borders to accommodate the gadget. 

Borders are adjusted only when the window is opened. Although the application can add and remove gadgets 
with AddGListQ and RemoveGList() after the window is opened, Intuition does not readjust the borders. 

A gadget may be placed into two borders by setting multiple border flags. If a gadget is to be placed in two 
borders, it only makes sense to put the gadget into adjoining borders. Setting both side border flags or both 
the top and bottom border flags for a particular gadget, will create a window that is all border. 

See the SuperBitMap example, lines.c, in the "Intuition Windows" chapter for an example of creating 
proportional gadgets that are positioned within a window's borders. 

There are circumstances where the border size will not adjust properly so that the gadget has the correct 
visual appearance. One way to correct this problem is to place a "hidden" gadget into the border, which forces 
the border to the correct size. Such a gadget would have no imagery and would not cause any IDCMP 
messages to be sent on mouse button activity. The gadget should be placed at the end of the gadget list of 
the window, so that it does not cover up any other border gadgets. 

Sometimes the sizing gadget can be used to adjust the width of the borders, as in the case of proportional 
gadgets in the right or bottom border. The proportional gadget will only increase the width of the border by 
enough so that the select box of the gadget fits within the border, no space is reserved between the gadget 
and the inner edge of the window. By placing the size gadget in both borders (using the window flags 
WFLG_SIZEBRIGHT and WFLG_SIZEBBOTTOM), the prop gadget sizes can be adjusted so that there is an 
even margin on all sides. This technique is used in the lines.c example mentioned above. 
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Figure 5-2: Size Gadget in Various Window Border Combinations 



The border flags GACT_RIGHTBORDER, GACT_RIGHTBORDER, GACT_TOPBORDER and 
GACTBOTTOM BORDER which are set in the Activation field of the Gadget structure declare that the 
gadget will be positioned in the border. Gadgets which are declared to be in the border are automatically 



refreshed by Intuition whenever the window borders need to be redrawn. This prevents the gadget imagery 
from being obliterated. 
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Some applications forgot to declare some of their gadgets as being in the border. While they looked fine prior 
to V36, they would have had some gadget imagery overwritten by the new style of window borders introduced 
with that release. To ensure compatibility with such applications, Intuition attempts to identify gadgets that are 
substantially in the border but do not have the appropriate border flags set. Such gadgets are marked for the 
same refresh treatment as explicit border gadgets. Applications should not rely on this behaviour, but should 
instead declare their border gadgets properly. 

Gadgets that are not declared to be in the border, and whose dimensions are 1 x 1 or smaller are never 
marked by Intuition as being effectively in the border. This is because some applications tuck a small 
nonselectable gadget (of size 0x0 or Ixl) into the window border, and attach imagery for the window to that 
gadget. The application does this to get automatic refresh of that imagery, since Intuition refreshes gadget 
imagery when window damage occurs. 

Beginning with V36, Intuition attempts to locate gadgets within the border that do not have the appropriate 
flags set. This may cause gadgets to appear in the border when the application has not set any of the border 
flags. Applications should not rely on this behaviour, nor should they place non-border gadgets fully or partially 
within the window's borders. 



Gadget Highlighting 



In general, the appearance of an active or selected gadget changes to inform the user the gadget state has 
changed. A highlighting method is specified by setting one of the highlighting flags in the Gadget structure's 
Flags field. 

Intuition supports three methods of activation or selection highlighting: 

Highlighting by color complementing (GFLG_GADGHCOMP) 

Highlighting by drawing a box (GFLG_GADGHBOX) 

Highlighting by an alternate image or border (GFLG_GADGHIMAGE) 

No highlighting (GFLG_GADGHNONE) 

One of the highlighting types or GFLG_GADGHNONE must be specified for each gadget. 

HIGHLIGHTING BY COLOR COMPLEMENTING 

Highlighting may be accomplished by complementing all of the colors in the gadget's select box. In this 
context, complementing means the complement of the binary number used to represent a particular color 
register. For example, if the color in color register 2 is used (binary 10) in a specific pixel of the gadget, the 
complemented value of that pixel will be the color in color register 1 (binary 01). 

To use this highlighting method, set the GFLG_GADGHCOMP flag. 

Only the select box of the gadget is complemented; any portion of the text, image, or border which is outside 
of the select box is not disturbed. See the chapter "Intuition Images, Line Drawing, and Text," for more 
information about complementing and about color in general. 
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HIGHLIGHTING BY DRAWING A BOX 

To highlight by drawing a simple border around the gadget's select box, set the GFLG_GADGHBOX bit in the 



Flags field. 

HIGHLIGHTING WITH AN ALTERNATE IMAGE OR ALTERNATE BORDER 

An alternate image may be supplied as highlighting for gadgets that use image rendering, similarly an 
alternate border may be supplied for gadgets that use border rendering. When the gadget is active or 
selected, the alternate image or border is displayed in place of the default image or border. For this 
highlighting method, set the SelectRender field of the Gadget structure to point to the Image structure or 
Border structure for the alternate display. 

Specify that highlighting is to be done with alternate imagery by setting the GFLG_GADGHIMAGE flag in the 
Flags field of the Gadget structure. When using GFLG_GADGHIMAGE, remember to set the 
GFLG_GADGIMAGE flag for images, clear it for borders. 

When using alternate images and borders for highlighting, gadgets rendered with images must highlight with 
another image and gadgets rendered with borders must highlight with another border. For information about 
how to create an Image or Border structure, see the chapter "Intuition Images, Line Drawing, and Text." 



Gadget Refreshing 



Gadget imagery is redrawn by Intuition at appropriate times, e.g., when the user operates the gadget. The 
imagery can also be updated under application control 

GADGET REFRESHING BY INTUITION 

Intuition will refresh a gadget whenever an operation has damaged the layer of the window or requester to 
which it is attached. Because of this, the typical application does not need to call RefreshGList() as a part of 
its IDCMP_REFRESHWINDOW event handling. 

Intuition's refreshing of the gadgets of a damaged layer is done through the layer's damage list. This means 
that rendering is clipped or limited to the layer's damage region-that part of the window or requester that 
needs refreshing. 

Intuition directly calls the Layers library functions BeginUpdateQ and EndllpdateQ, so that rendering is 
restricted to the proper area. Applications should not directly call these functions under Intuition, instead, use 
the BeginRefresh() and EndRefreshQ calls. Calls to RefreshGList() or RefreshGadgetsQ between 
BeginRefresh() and EndRefreshQ are not permitted. Never add or remove gadgets between the 
BeginRefreshQ and EndRefresh() calls. 

For more information on Beg in Refresh () and EndRefresh(), see the "Intuition Windows" chapter and the 
Amiga ROM Kernel Reference Manual: Includes and Autodocs. 

Gadgets which are positioned using GFLG_RELBOTTOM or GFLG_RELRIGHT, or sized using 
GFLG_RELWIDTH or GFLG_RELHEIGHT pose a problem for this scheme. When the window is sized, 
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the images for these gadgets must change, even though they are not necessarily in the damage region. 
Therefore, Intuition must add the original and new visual regions for such relative gadgets to the damage 
region before refreshing the gadgets. The result of this is that applications should ensure that any gadgets 
with relative position or size do not have Border, Image or IntuiText imagery that extends beyond their select 
boxes. 

GADGET REFRESHING BY THE PROGRAM 

The AddGListQ function adds gadgets to Intuition's internal lists but do not display their imagery. 
Subsequently calls to RefreshGList() must be made to draw the gadgets into the window or requester. 

Programs may use RefreshGListQ to update the display after making changes to their gadgets. The 
supported changes include (not an exhaustive list): changing the GFLG_SELECTED flag for boolean gadgets 



to implement mutually exclusive gadgets, changing the GadgetText of a gadget to change its label, changing 
the GFLG_DISABLED flag, and changing the contents of the Stringlnfo structure Buffer of a string gadget. 
When making changes to a gadget, be sure to remove the gadget from the system with RemoveGList() 
before altering it. Remember to add the gadget back and refresh its imagery. 

Boolean gadgets rendered with borders, instead of images, or highlighted with surrounding boxes 
(GFLG_GADGHBOX) are handled very simply by Intuition, and complicated transitions done by the program 
can get the rendering out of phase. Applications should avoid modifying the imagery and refreshing gadgets 
that may be highlighted due to selection by the user. Such operations may leave pixels highlighted when the 
gadget is no longer selected. The problems with such transitions can often be avoided by providing imagery, 
either image or border, that covers all pixels in the select box. For GFLG_GADGHIMAGE gadgets, the select 
imagery should cover all pixels covered in the normal imagery. 

Updating a Gadgets Imagery 

The RefreshGListQ function was designed to draw gadgets from scratch, and assumes that the underlying 
area is blank. This function cannot be used blindly to update gadget imagery. The typical problem that arises 
is that the application cannot change a gadget from selected to unselected state (or from disabled to enabled 
state) and have the imagery appear correct. However, with a little care, the desired results can be obtained. 

Depending on the imagery you select for your gadget, the rendering of one state may not completely 
overwritten the rendering of a previous one. For example, consider a button which consists of a 
complement-highlighted boolean gadget, whose imagery is a surrounding Border and whose label is an 
IntuiText. Attempting to visually unselect such a gadget by clearing its GFLG_SELECTED flag and refreshing 
it will leave incorrect imagery because RefreshGListQ just redraws the border and text, and never knows to 
erase the field area around the text and inside the gadget. That area will remain complemented from before. 

One solution is to use a gadget whose imagery is certain to overwrite any imagery left over from a different 
state. Disabling a gadget or highlighting it with complement mode affects the imagery in the entire select box. 
To overwrite this successfully, the gadget's imagery (GadgetRender) should be an Image structure which 
fully covers the select box. Such a gadget may be highlighted with color complementing 
(GFLG_GADGHCOMP), or with an alternate image (GFLG_GADGHIMAGE) for its SelectRender. Or, for a 
gadget which will never be disabled but needs to be deselected programmatically, you may also use a Border 
structure for its GadgetRender, and an identically-shaped (but differently COLOURED) Border for its 
SelectRender. 

Intuition Gadgets 129 

The other technique is to pre-clear the underlying area before re-rendering the gadget. To do this, remove the 
gadget, erase the rectangle of the gadget's select area, change the GFLG_SELECTED or the 
GFLG_DISABLED flag, add the gadget back, and refresh it. 

If the gadget has a relative size and/or position (i.e., if of the GFLG_RELxxx flags are used), then the 
application will need to compute the rectangle of the gadget's select area based on the window's current width 
and/or height. Since the window size is involved in the calculation, it is important that the window not change 
size between the call to RemoveGList() and the call to RectFill(). To ensure this, the application should set 
IDCMP_SIZEVERIFY so that Intuition will first notify you before beginning a sizing operation. (Note that 
applications using any of the IDCMP verify events such as IDCMP_SIZEVERIFY should not delay long in 
processing such events, since that holds up the user, and also Intuition may give up and stop waiting for you). 

Gadget Refresh Function 

Use the RefreshGList() function to refresh one or more gadgets in a window or requester. 

void Ref reshGList ( struct Gadget -gadgets, struct Window *window, 
struct Requester *requester, long numGad ) ; 

This function redraws no more than numGad gadgets, starting with the specified gadget, in a window or 
requester. The application should refresh any gadgets after adding them. The function should also be used 
after the application has modified the imagery of the gadgets to display the new imagery. 



Gadget Enabling and Disabling 

A gadget may be disabled so that it cannot be chosen by the user. When a gadget is disabled, its image is 
ghosted. A ghosted gadget is overlaid with a pattern of dots, thereby making the imagery less distinct. The 
dots are drawn into the select box of the gadget and any imagery that extends outside of the select box is not 
affected by the ghosting. 

The application may initialize whether a gadget is disabled by setting the GFLG_DISABLED flag in the 
Gadget structure's Flags field before a gadget is submitted to Intuition. Clear this flag to create an enabled 
gadget. 

After a gadget is submitted to Intuition for display, its current enable state may be changed by calling 
OnGadget() or OffGadgetQ. If the gadget is in a requester, the requester must currently be displayed when 
calling these functions. 

void OnGadget ( struct Gadget *gadget, struct Window *window, struct Requester Requester ); 
void OffGadget( struct Gadget *gadget, struct Window *window, struct Requester Requester ); 

Depending on what sort of imagery you choose for your gadget, OnGadget() may not be smart enough to 
correct the gadget's displayed imagery. See the section on "Updating a Gadget's Imagery" for more details. 

Multiple gadgets may be enabled or disabled by calling OnGadgetQ or OffGadgetQ for each gadget, or by 
removing the gadgets with RemoveGList(), setting or clearing the GFLG_DISABLED flag on each, replacing 
the gadgets with AddGList(, and refreshing with RefreshGList(). 
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Gadget Pointer Movements 

If the GACT_FOLLOWMOUSE flag is set for a gadget, the application will receive mouse movement 
broadcasts as long as the gadget is active. This section covers the behaviour of proportional, boolean and 
string gadgets, although there are major caveats in some cases: 

Unlike IDCMP_GADGETUP and IDCMP_GADGETDOWN IntuiMessages, the lAddress field of an 
IDMP_MOUSEMOVE IntuiMessage does not point to the gadget. The application must track the 
active gadget (this information is readily obtained from the IDCMP_GADGETDOWN message) 
instead of using the lAddress field. 

Right Wrong 

imsg=GetMsg (win->UserPort) ; imsg=GetMsg (win->UserPort) ; 

class=imsg->Class ; class=imsg->Class ; 

code=imsg- >Code ; code=imsg- >Code ; 

/* OK */ /* ILLEGAL ! */ 

iaddres S = imsg-> lAddress ; gadid=( (struct Gadget *) imsg->IAddress) ->GadgetID; 

ReplyMsg (imsg) ; ReplyMsg (imsg) ; 

Using the code in the left column, it is acceptable to get the address of a gadget with gadid=((struct 
Gadget *)iaddress)->GadgetlD but only after you have checked to make sure the message is an 
IDCMP_GADGETUP or IDCMP_GADGETDOWN. 

Boolean gadgets only receive mouse messages if both GACT_RELVERIFY and 
GACT_FOLLOWMOUSE are set. Those cases described below with GACT_RELVERIFY cleared do 
not apply to boolean gadgets. 

In general, IDCMP_MOUSEMOVE messages are sent when the mouse changes position while the 
gadget is active. Boolean and proportional gadgets are active while the mouse button is held down, 
thus mouse move messages will be received when the user "drags" with the mouse. String gadgets 



arc active until terminated by keyboard entry or another object becomes active (generally by user 
clicking the other object). GACT_FOLLOWMOUSE string gadgets will generate mouse moves the 
entire time they are active, not just when the mouse button is held. 

The broadcasts received differ according to the gadget's flag settings. If using the GACTJMMEDIATE and 
GACT_RELVERIFY activation flags, the program gets a gadget down message, receives mouse reports 
(IDCMP_MOUSEMOVE) as the mouse moves, and receives a gadget up message when the mouse button is 
released. For boolean gadgets, the mouse button must be released while the pointer is over the gadget. If the 
button is not released over the boolean gadget, an IDCMP_MOUSEBUTTONS message with the SELECTUP 
qualifier will be sent. 

If only using the GACTJMMEDIATE activation flag, the program gets a gadget down message and receives 
mouse reports as the mouse moves. The mouse reports will stop when the user releases the mouse select 
button. This case does not apply to boolean gadgets as GACT_RELVERIFY must be set for boolean gadgets 
to receive mouse messages. If only using the GACT_RELVERIFY activation flag, the program gets mouse 
reports followed by an up event for a gadget. For boolean gadgets, the IDCMP_GADGETUP event will only be 
received if the button was released while the pointer was over the gadget. If the button is not released over the 
boolean gadget, a IDCMP_MOUSEBUTTONS message with the SELECTUP qualifier will be received if the 
program is receiving these events. 

If neither the GACTJMMEDIATE nor the GACTJ=iELVERIFY activation flags are set, the program will only 
receive mouse reports. This case does not apply to boolean gadgets as GACTRELVERIFY must beset for 
boolean gadgets to receive mouse messages. 
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Gadget Structure 

Here is the specification for the Gadget structure defined in <intuition/intuition.h>. You create an instance of 
this structure for each gadget you place in a window or requester: 

struct Gadget 

{ 

struct Gadget *NextGadget ; 

WORD LeftEdge, TopEdge; 

WORD Width, Height; 

UWORD Flags; 

UWORD Activation; 

UWORD GadgetType; 

APTR GadgetRender; 

APTR SelectRender; 

struct IntuiText *GadgetText; 

LONG MutualExclude; 

APTR Speciallnfo; 

UWORD GadgetID; 

APTR UserData; 
} 

NextGadget 

Applications may create lists of gadgets that may be added to a window or requester with a single 
instruction. NextGadget is a pointer to the next gadget in the list. The last gadget in the list should 
have a NextGadget value of NULL. 

When gadgets are added or removed, Intuition will modify the appropriate NextGadget fields to 
maintain a correctly linked list of gadgets for that window or requester. However, removing one or 
more gadgets does not reset the last removed gadget's NextGadget field to NULL. 

LeftEdge, TopEdge, Width, Height 

These variables describe the location and dimensions of the select box of the gadget. Both location 
and dimensions can be either absolute values or else relative to the edges and size of the window or 
requester chat contains the gadget. 



Flags 



LeftEdge and TopEdge are relative to one of the corners of the display element, according to how 
GFLG_RELRIGHT and GFLG_RELBOTTOM are set in the Flags variable (see below). 

Width and Height are either absolute dimensions or a negative increment to the width and height of a 
requester or a window, according to how the GFLG_RELWIDTH and GFLG_RELHEIGHT flags are 
set (see below). 



The Flags field is shared by the program and Intuition. See the section below on "Gadget Flags" for a 
complete description of all the flag bits. 



Activation 

This field is used for information about some gadget attributes. See the "Gadget Activation Flags" 
section below for a description of the various flags. 
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GadgetType 

This field contains information about gadget type and in what sort of display element the gadget is to 
be displayed. One of the following flags must be set to specify the type: 

GTYP_BOOLGADGET 

Boolean gadget type. 

GTYP_STRGADGET 

String gadget type. For an integer gadget, also set the GACT_LONGINT flag. See the 
"Gadget Activation Flags" section below. 

GTYP_PROPGADGET 

Proportional gadget type. 

GTYP_CUSTOMGADGET 

Normally not set by the application. Used by custom BOOPSI gadget types, discussed in 
the "BOOPSI" chapter. 

The following gadget types may be set in addition to one of the above types. None of the following 
types are required: 

GTYPJ3ZZGADGET 

If the gadget is placed in a GimmeZeroZero window, setting this flag will place the gadget in 
the border layer, out of the inner window. If this flag is not set, the gadget will go into the 
inner window. Do not set this bit if this gadget is not placed in a GimmeZeroZero window. 

GTYP_REQGADGET 

Set this bit if this gadget is placed in a requester. 

GadgetRender 

A pointer to the Image or Border structure containing the graphics imagery of this gadget. If this field 
is set to NULL, no rendering will be done. 

If the graphics of this gadget are implemented with an Image structure, this field should contain a 
pointer to that structure and the GFLG_GADGIMAGE flag must be set. If a Border structure is used, 
this field should contain a pointer to the Border structure, and the GFLG_GADGIMAGE bit must be 
cleared. 

SelectRender 

If the application does not use an alternate image for highlighting, set this field to NULL. Otherwise, if 
the flag GFLG_GADGHIMAGE is set, this field must contain a pointer to an Image or Border 
structure. The GFLG_GADGIMAGE flag determines the type of the rendering. Provide a pointer to an 
IntuiText structure to include a text component to the gadget. Multiple IntuiText structures may be 
chained. Set this field to NULL if the gadget has no associated text. 



GadgetText 

Provide a pointer to an IntuiText structure to include a text component to the gadget. Multiple 
IntuiText structures may be chained. Set this field to NULL if the gadget has no associated text. 

The offsets in the IntuiText structure are relative to the top left of the gadget's select box. 
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Mutual Exclude 

This field is currently ignored by Intuition, but is reserved. Do not store information here. Starting with 
V36, if the GadgetType is GTYP_CUSTOMGADGET this field is used to point to a Hook for the 
custom gadget. 

Speciallnfo 

Speciallnfo contains a pointer to an extension structure which contains the special information 
needed by the gadget. 

If this is a proportional gadget, this variable must contain a pointer to an instance of a Proplnfo data 
structure. If this is a string or integer gadget, this variable must contain a pointer to an instance of a 
Stringlnfo data structure. If this is a boolean gadget with GACT_BOOLEXTEND activation, this 
variable must contain a pointer to an instance of a Boollnfo data structure. Otherwise, this variable is 
ignored. 

GadgetID 

This variable is for application use and may contain any value. It is often used to identify the specific 
gadget within an event processing loop. This variable is ignored by Intuition. 

UserData 

This variable is for application use and may contain any value. It is often used as a pointer to a data 
block specific to the application or gadget. This variable is ignored by Intuition. 

GADGET FLAGS 

The following are the flags that can be set in the Flags variable of the Gadget structure. There are four 
highlighting methods to choose from. These determine how the gadget imagery will be changed when the 
gadget is selected. One of these four flags must be set. 

GFLG_GADGHNONE 

Set this flag for no highlighting. 

GFLGJ3ADGHCOMP 

This flag chooses highlighting by complementing all of the bits contained within the gadget's select 
box. 

GFLG_GADGHBOX 

This flag chooses highlighting by drawing a complemented box around the gadget's select box. 

GFLG_GADGHIMAGE 

Set this flag to indicate highlighting with an alternate image. 

In addition to the highlighting flags, these other values may be set in the Flags field of the Gadget structure. 

GFLGJ3ADGIMAGE 

If the gadget has a graphic, and it is implemented with an Image structure, set this bit. If the graphic 
is implemented with a Border structure, make sure this bit is clear. This bit is also used by 
SelectRender to determine the rendering type. 
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GFLG_RELBOTTOM 

Set this flag if the gadget's TopEdge variable describes an offset relative to the bottom of the display 
element (window or requester) containing it. A GFLG_RELBOTTOM gadget moves automatically as 
its window is made taller or shorter. Clear this flag if TopEdge is relative to the top of the display 
element. If GFLG_RELBOTTOM is set, TopEdge should contain a negative value, which will position 
it up from the bottom of the display element. 

GFLG_RELRIGHT 

Set this flag if the gadget's LeftEdge variable describes an offset relative to the right edge of the 
display element containing it. A GFLG_RELRIGHT gadget moves automatically as its window is 
made wider or narrower. Clear this flag if LeftEdge is relative to the left edge of the display element. 
If GFLG_RELRIGHT is set, LeftEdge should contain a negative value, which will position the gadget 
left of the right edge of the display element. 

GFLG_RELWIDTH 

Set this flag for "relative gadget width." If this flag is set, the width of the gadget's select box changes 
automatically whenever the width of its window changes. When using GFLG_RELWIDTH, set the 
gadget's Width to a negative value. This value will be added to the width of the gadget's display 
element (window or requester) to determine the actual width of the gadget's select box. 

GFLG_RELHEIGHT 

Set this flag for "relative gadget height." If this flag is set, the height of the gadget's select box 
changes automatically whenever the height of its window changes. When using GFLG_RELHEIGHT, 
set the gadget's Height to a negative value. This value will be added to the height of the gadget's 
display element (window or requester) to determine the actual height of the gadget's select box. 

GFLG_SELECTED 

Use this flag to preset the on/off selected state for a toggle-select boolean gadget (see the discussion 
of the GACT_TOGGLESELCT flag below). If the flag is set, the gadget is initially selected and is 
highlighted. If the flag is clear, the gadget starts off in the unselected state. To change the selection 
state of one or more gadgets, change their GFLG_SELECTED bits as appropriate, add them back 
and refresh them. However, see the section on "Updating a Gadget's Imagery" for important details. 

GFLG_DISABLED 

If this flag is set, this gadget is disabled. To enable or disable a gadget after the gadget has been 
added to the system, call the routines OnGadget() and OffGadget(). The GFLG_DISABLED flag can 
be programmatically altered in much the same way as GFLG_SELECTED above. See the section on 
"Updating a Gadget's Imagery" for important details. 

GFLG_STRINGEXTEND 

The Stringlnfo Extension field points to a valid StringExtend structure. Use of this structure is 
described later in the "String Gadget Type" section of this chapter. This flag is ignored prior to V37, 
see GACT_STRINGEXTEND for the same functionality under V36. Note that 
GACT_STR I NG EXTEND is not ignored prior to V36 and should only be set in V36 or later systems. 

GFLG_TABCYCLE 

This string participates in cycling activation with the tab (or shifted tab) key. If this flag is set, the tab 
keys will de-activate this gadget as if the Return or Enter keys had been pressed, sending an 
IDCMP_GADGETUP message to the application, then the next string gadget with GFLG_TABCYCLE 
set will be activated. Shifted tab activates the previous gadget. 
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GADGET ACTIVATION FLAGS 

These flags may be set in the Activation field of the Gadget structure. 

GACT_TOGGLESELECT 

This flag applies only to boolean gadgets, and tells Intuition that this is to be a toggle-select gadget, 
not a hit-select one. Preset the selection state with the gadget flag GFLG_SELECTED (see above). 
The program may check if the gadget is in the selected state by examining the GFLG_SELECTED 



flag at any time. 

GACTJMMEDIATE 

If this bit is set, the program will be sent an IDCMP_GADGETDOWN message when the gadget is 
first picked. The message will be sent when the user presses the mouse select button. 

GACT_RELVERIFY 

This is short for "release verify." If this bit is set, the program will be sent an IDCMP_GADGETUP 
message when the gadget is deactivated. IDCMP_GADGETUP will be sent for boolean gadgets 
when the user releases the mouse select button while the pointer is over the select box, for 
proportional gadgets whenever the user releases the mouse select button (regardless of the pointer 
position), and for string and integer gadgets when the user completes the text entry by pressing 
return or tabbing to the next gadget (where supported). 

For boolean gadgets, if the user releases the mouse button while the pointer is outside of the 
gadget's select box IDCMP_GADGETUP will not be generated. Instead, the program will receive an 
IDCMP_MOUSEBUTTONS event with the SELECTUP code set. For string gadgets, if the user 
deactivates the gadget by clicking elsewhere, it may not be possible to detect. 

GACT_ENDGADGET 

This flag pertains only to gadgets attached to requesters. If a gadget with the GACT_ENDGADGET 
flag set is chosen by the user the requester will be terminated as if the application had called the 
EndRequestQ function. 

See the chapter "Intuition Requesters and Alerts," for more information about requester gadget 
considerations. 

GACT_FOLLOWMOUSE 

These flags may be set in the Activation field of the Gadget structure. As long as a gadget that has 
this flag set is active, the program will receive mouse position messages for each change of mouse 
position. For GTYP_BOOLGADGET gadgets, GACT_RELVERIFY must also be set for the program 
to receive mouse events. 

The following flags are used to place application gadgets into a specified window border. Intuition will adjust 
the size of a window's borders appropriately provided these gadgets are set up with a call to OpenWindow(), 
OpenWindowTagsQ or OpenWindowTagListQ. Intuition knows to refresh gadgets marked with these flags 
when the window border is changed, e.g., when the window is activated. For GimmeZeroZero windows, the 
GTYP_GZZGADGET flag must also be set for border gadgets. 

GACT_RIGHTBORDER 

If this flag is set, the gadget is placed in the right border of the window and the width and position of 
this gadget are used in deriving the width of the window's right border. 
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GACTJ.EFTBORDER 

If this flag is set, the gadget is placed in the left border of the window and the width and position of 
this gadget are used in deriving the width of the window's left border. 

GACT_TOPBORDER 

If this flag is set, the gadget is placed in the top border of the window and the height and position of 
this gadget are used in deriving the height of the window's top border. 

GACT_BOTTOMBORDER 

If this flag is set, the gadget is placed in the bottom border of the window and the height and position 
of this gadget are used in deriving the height of the window's bottom border. 

The following flags apply only to string gadgets: 

GACT_STRINGCENTER 

If this flag is set, the text in a string gadget is centered within the select box. 



GACT_STRINGRIGHT 

If this flag is set, the text in a string gadget is right justified within the select box. 

GACT_STRINGLEFT 

This "flag" has a value of zero. By default, the text in a string gadget is left justified within the select 
box. 

GACTJ.ONGINT 

If this flag is set, the user can construct a 32-bit signed integer value in a normal string gadget. The 
input buffer of the string gadget must be initialized with an ASCII representation of the starting integer 
value. 

GACT_ALTKEYMAP 

These flags may be set in the Activation field of the Gadget structure. A pointer to the keymap must 
be placed in the Stringlnfo structure variable AltKeyMap. 

GACT_BOOLEXTEND 

This flag applies only to boolean gadgets. If this flag is set, then the boolean gadget has a Boollnfo 
structure associated with it. A pointer to the Boollnfo structure must be placed in the Speciallnfo 
field of the Gadget structure. 

GACT_STRINGEXTEND 

This is an obsolete flag originally defined in V36. It applies only to string gadgets and indicates that 
Stringlnfo.Extension points to a valid StringExtend structure. Although this flag works, it is not 
ignored prior to V36 as it should be in order to be backward compatible. This flag is replaced by 
GFLG_STRINGEXTEND in V37. GFLG_STRINGEXTEND performs the same function and is 
properly ignored on systems prior to V36. 
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Boolean Gadget Type 

A boolean gadget gets yes/no or on/off responses from the user. To make a boolean gadget set the 
GadgetType field to GTYP_BOOLGADGET in the Gadget structure. 

Boolean gadgets come in two types: hit-select and toggle-select. Hit-select gadgets are only active while the 
user holds down the mouse select button. When the button is released, the gadget is unhighlighted. Action 
buttons, such as "OK" and "Cancel", are hit-select. 

Toggle-select gadgets become selected when the user clicks them. To "unselect" the gadget, the user has to 
click the gadget again. Switches, such as a checkbox, are toggle-select. 

Set the GACT_TOGGLESELECT flag in the Activation field of the Gadget structure to create a toggle select 
gadget. 

The GFLG_SELECTED flag in Gadget structure Flags field determines the initial and current on/off selected 
state of a toggle-select gadget. If GFLG_SELECTED is set, the gadget will be highlighted. The application can 
set the GFLG_SELECTED flag before submitting the gadget to Intuition. The program may examine this flag 
at any time to determine the current state of this gadget. 

Try to make the imagery for toggle-select gadgets visually distinct from hit-select gadgets so that their 
operation can be determined by the user through visual inspection. 

MASKED BOOLEAN GADGETS 

Imagery for boolean gadgets is rectangular by default, but non-rectangular boolean gadgets are possible, with 
some restrictions. An auxiliary bit plane, called a mask, may be associated with a boolean gadget. When the 
user clicks within the select box of the gadget, a further test is made to see if the chosen point is .contained 
within the mask. Only if it is, does the interaction count as a gadget hit. 



With masked boolean gadgets, if the gadget has highlight type GFLG_GADGHCOMP then them complement 
rendering is restricted to the mask. This allows for non-rectangular shapes, such as an oval gadget which 
highlights only within the oval. 

There are some shortcomings to non-rectangular boolean gadgets. For instance, the gadget image is not 
rendered through the mask. Images are rectangular blocks, with all bits rendered. In the case of an oval mask, 
the image will be rendered in the corner areas even though they are outside of the oval. Also, it is not possible 
to mask out the select box, thus non-rectangular masked gadgets cannot overlap in the masked area. 
Therefore, such gadgets can't be crowded together without care. Likewise, the ghosting of a disabled gadget 
does not respect the mask, so ghosting of the corners around an oval may be visible, depending on the colors 
involved. 

To use a masked boolean gadget, fill out an instance of the Boollnfo structure. This structure contains a 
.pointer to the mask plane data. The application must also set the GACT_BOOLEXTEND flag in the gadget's 
Activation field. 
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BOOLINFO STRUCTURE 

This is the special data structure required for a masked boolean gadget. A pointer to this structure must be 
placed in the gadget's Speciallnfo field for a masked boolean gadget. 

struct Boollnfo 

{ 

UWORD Flags; 

UWORD Mask; 

ULONG Reserved; 
) ; 

Flags 



Mask 



Flags must be given the value BOOLMASK. 

This is a bit mask for highlighting and picking the gadget. Construct the mask as a single plane of 
Image data would be built. The image's width and height are determined by the width and height of 
the gadget's select box. The mask data must be in chip memory. 

Reserved 

Set this field to NULL 

MUTUAL EXCLUDE 

Mutual exclusion of boolean gadgets (sometimes referred to as "radio buttons") is not directly supported by 
Intuition. This section describes the method an application should use to implement this feature. It is up to the 
application to handle the manipulation of excluded gadgets in an Intuition compatible way. The program must 
proceed with caution so as to maintain the synchronization of the gadget and its imagery. The rules provided 
in this section for the implementation of mutual exclude gadgets minimize the risk and complexity of the 
application. Other techniques may seem to work with simple input, but may fail in subtle ways when stressed. 

Gadget Type for Mutual Exclusion 

To implement mutual exclusion, gadgets must be hit-select (not GACT_TOGGLESELECT) boolean gadgets, 
with the GACTJMMEDIATE activation type (never GACT_RELVERIFY). All state changes must be executed 
upon receiving the IDCMP_GADGETDOWN message for the gadgets. Failure to do this could introduce 
subtle out-of-phase imagery problems. 

Gadget Highlighting for Mutual Exclusion. 

When using complement mode highlighting, the image supplied must be at least the size of the complemented 
area (the gadget select box). An extended boolean gadget with a mask may be used to constrain the area that 



is highlighted. 

Alternate image highlighting may be used provided the two images have exactly the same size and position. 
Likewise, a border and alternate border may be used provided the two borders are identical in shape and 
position, differing only in color. 
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Do not use other combinations for mutual exclude gadgets such as a gadget with a border that uses 
complement mode highlighting or a gadget which uses highlighting by drawing a box. See the section on 
"Updating a Gadget's Imagery" for more information. 

Handling of Mutually Exclusive Gadgets 

Use RemoveGListQ to remove the boolean gadget from the window or requester. Set or clear the 
GFLG_SELECTED flag to reflect the displayed state of the gadget. Replace the gadget using AddGList() and 
refresh its imagery with RefreshGList(). Of course, several gadgets may be processed with a single call to 
each of these functions. 



Proportional Gadget Type 



Proportional gadgets allow an application to get or display an amount, level, or position by moving a slidable 
knob within a track. They are called proportional gadgets because the size and position of the knob is 
proportional to some application-defined quantity, for example the size of a page, and how much and which 
part of the page is currently visible. 

An example of using proportional gadgets is available in the "Intuition Windows" chapter. The SuperBitMap 
window example, lines. c, uses proportional gadgets to control the position of the bitmap within the window. 

Proportional gadgets are made up of a container, which is the full size of the gadget, and a knob, that travels 
within the container. Changing the current value of the gadget is done by dragging the knob, or clicking in the 
container around the knob. Dragging the knob performs a smooth transition from one value to the next, while 
clicking in the container jumps to the next page or setting. The KNOBHIT flag in the Proplnfo structure is 
available to allow the program to determine if the gadget was changed by dragging the knob or by clicking in 
the container. If the flag is set, the user changed the value by dragging the knob. 

Proportional gadgets allow display and control of fractional settings on the vertical axis, the horizontal axis or 
both. While the number of settings has a theoretical limit of 65,536 positions, the actual positioning of the 
gadget through sliding the knob is limited by the resolution of the screen. Further control is available by 
clicking in the container, although this often is not convenient for the user. Button or arrow gadgets are often 
provided for fine tuning of the setting of the gadget. 

NEW 3D LOOK PROPORTIONAL GADGETS 

Set the PROPNEWLOOK flag in the Proplnfo Flags field to get the new 3D look. The new 3D look laid 
proportional gadgets have a dithered pattern in the container and updated knob imagery. The knob 
dimensions are also slightly changed for those proportional gadgets with a border. 

Set the PROPBORDERLESS flag in the Proplnfo Flags field if no border around the container is desired. 
Setting this flag with PROPNEWLOOK will provide a 3D knob. 

Proportional gadgets and the New 3D Look. To create prop gadgets that have the same 
look as the rest of the system, set the PROPNEWLOOK flag and clear the 
PROPBORDERLESS flag. It is recommended that applications follow this guideline to 
maintain a compatible look and feel for all gadgets in the system. 
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New look proportional gadgets placed in the border of a window will change to an inactive 
display state when the window is deactivated. This only happens to gadgets that have the 



PROPNEWLOOK flag set and are in the window border. In the inactive state, the knob is 
filled with BACKGROUNDPEN. 

LOGICAL TYPES OF PROPORTIONAL GADGETS 

There are two usual ways in which proportional gadgets are used (corresponding to the scroller and slider 
gadgets of the GadTools library). The only difference between sliders and scrollers is the way they are 
managed internally by the application. The GadTools library provides a high level interface to proportional 
gadgets, simplifying the management task for these types of objects. 

Scrollers 

The scroller controls and represents a limited window used to display a large amount of data. For instance, a 
text editor may be operating on a file with hundreds of lines, but is only capable of displaying twenty or thirty 
lines at a time. 

In a scroller, the container of the gadget is analogous to the total amount of data, while the knob represents 
the window. (Note that window here is used as an abstract concept and does not necessarily mean \ntuition 
window. It just means a display area reserved for viewing the data.) 

The size of the knob with respect to its container is proportional to the size of the window with respect to the 
total data. Thus, if the window can display half the data, the knob should be half the size of the container. 
When the amount of data is smaller than the window size, the knob should be as large as its container. 

The position of the knob with respect to its container is also proportional to the position of the window with 
respect to the total data. Thus, if the knob starts half way down the container, the top of the window should 
display information half way into the data. 

Scrollers may be one or two dimensional. One dimensional scrollers are used to control linear data; such as a 
text file, which can be viewed as a linear array of strings. Such scrollers only slide on a single axis. 

Two dimensional scrollers are used to control two dimensional data, such as a large graphic image. Such a 
scroller can slide on both the horizontal and vertical axes, and the knob's horizontal and vertical size and 
position should be proportional to the window's size and position in the data set. 

Multi-dimensional data may also be controlled by a number of one dimensional scrollers, one for each axis. 
The Workbench windows provide an example of this, where one scroller is used for control of the x-axis of the 
window and another scroller is used for control of the y-axis of the window. In this case, the size and position 
of the knob is proportional to the size and position of the axis represented by the gadget. 

If the window has a sizing gadget and has a proportional gadget is the right or bottom border, the sizing 
gadget is usually placed into the border containing the proportional gadget, as the border has already been 
expanded to contain the gadget. If the window has proportional gadgets in both the right and the bottom 
borders, place the sizing gadget into both borders. This creates evenly sized borders that match the height 
and width of the sizing gadget, i.e. it is only done for visual effect. 
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Sliders 

The slider is used to pick a specific value within a set Usually the set is ordered, but this is not required. An 
example of this would be choosing the volume of a sound, the speed of an animation or the brightness of a 
color. Sliders can move on either the vertical or horizontal axis. A slider that moves on both the horizontal and 
the vertical axis could be created to choose two values at once. 

An example slider which picks an integer between one and ten, should have the following attributes: 

It should slide on only one axis. 

Values should be evenly distributed over the length of the slider. 



Clicking in the container to either side of the knob should increase (or decrease) the value by one 
unit 

Stylistically, sliding the knob to the right or top should increase the value, while sliding it to the left or down 
should decrease the value. Note that the orientation of proportional gadgets is correct for scrollers (where the 
minimum value is topmost or leftmost), but is vertically inverted for sliders. Thus, well-behaved vertical sliders 
need to invert their value somewhere in the calculations (or else the maximum will end up at the bottom). 

PROPORTIONAL GADGET COMPONENTS 

A proportional gadget has several components that work together. They are the container, the knob, the pot 
variables and the body variables. 

The Container 

The container is the area in which the knob can move. It is actually the select box of the gadget. The size of 
the container, like that of any other gadget select box, can be relative to the size of the window. The position 
of the container can be relative to any of the Intuition window's border. 

Clicking in the container around the knob will increment or decrement the value of the gadget (the pot 
variables) by the appropriate amount (specified in the body variables). The knob will move towards the point 
clicked when action is taken. 

The Knob 

The knob may be manipulated by the user to quickly change the pot variables. The knob acts like a real world 
proportional control. For instance, a knob restricted to movement on a single axis can be thought of as a 
control such as the volume knob on a radio. A knob that moves on both axes is analogous to the control stick 
of an airplane. 

The user can directly move the knob by dragging it on the vertical or horizontal axis. The knob may be 
indirectly moved by clicking within the select box around the knob. With each click, the pot variable is 
increased or decreased by one increment, defined by the settings of the body variables. 

The current position of the knob reflects the pot value. A pot value of zero will place the knob in the top or 
leftmost position, a value of MAXPOT will place the knob at the bottom or rightmost position. 
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The application can provide its own imagery for the knob or it may use Intuition's auto-knob. The auto- knob is 
a rectangle that changes its width and height according to the current body settings. The auto-knob is 
proportional to the size of the gadget. Therefore, an auto-knob can be used in a proportional gadget whose 
size is relative to the size of the window, and the knob will maintain the correct size, relative to the size of the 
container. 

Use Separate Imagery for Proportional Gadgets. These Image structures may not be 
shared between proportional gadgets, each must have its own. Again, do not share the 
Image structures between proportional gadgets. This does not work, either for auto-knob 
or custom magery. 

Use Only One Image for the Knob. Proportional gadget knob images may not be a list of 
images. These must be a single image, initialized and ready to display if a custom image 
is used for the knob. 

The Pot Variables 

The HorizPot and VertPot variables contain the actual proportional values entered into or displayed by the 
gadget. The word pot is short for potentiometer, which is an electrical analog device used to adjust a value 
within a continuous range. 

The proportional gadget pots allow the program to set the current position of the knob within the container, or 



to read the knob's current location. 

The pot variable is a 16-bit, unsigned variable that contains a value ranging from zero to OxFFFF. For clarity, 
the constant MAXPOT is available, which is equivalent to OxFFFF. A similar constant MAXBODY is available 
for the body variables. As the pot variables are only 16 bits, the resolution of the proportional gadgets has a 
maximum of 65,536 positions (zero to 65,535). 

The values represented in the pot variables are usually translated or converted to a range of numbers more 
useful to the application. For instance, if a slider covered the range one to three, pot values of zero to 16,383 
would represent one, values of 16,384 to 49,151 would represent two and values of 49,152 to 65,535 would 
represent three. The method of deriving these numbers is fairly complex, refer to the sample code 'below for 
more information. 

There are two pot variables, as proportional gadgets are adjustable on the horizontal axis, the vertical axis or 
both. The two pot variables are independent and may be initialized to any 16-bit, unsigned value. 

Pot values change while the user is manipulating the gadget. The program may read the values in the pots at 
any time after it has submitted the gadget to the user via Intuition. The values always have the current settings 
as adjusted by the user. 

The Body Variables 

The HorizBody and VertBody variables describe the standard increment by which the pot variables change 
and the relative size of the knob when auto-knob is used. The increment, or typical step value, is the value 
added to or subtracted from the internal knob position when the user clicks in the container around the knob. 
For example, a proportional gadget for color mixing might allow the user to add or subtract 1/16 of the full 
value each time, thus the body variable should be set to MAXBODY / 1 6. 
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Body variables are also used in conjunction with the auto-knob (described above) to display for the user how 
much of the total quantity of data is displayed. Additionally, the user can tell at a glance that clicking in the 
container around the knob will advance the position by an amount proportional to the size of the knob. 

For instance, if the data is a fifteen line text file, and five lines are visible in the display, then the body variable 
should be set to one third of MAXBODY. In this case, the auto-knob will fill one third of the container, and 
clicking in the container ahead of the knob will advance the position in the file by one third. 

For a slider, the body variables are usually set such that the full percentage increment is represented. This is 
not always so for a scroller. With a scroller, some overlap is often desired between successive steps. For 
example, when paging through a text editor, one or two lines are often left on screen from the previous page, 
making the transition easier on She user. 

The two body variables may be set to the same or different increments. When the user clicks in the container, 
the pot variables are adjusted by an amount derived from the body variables. 

Using the Body and Pot Values 

The body and pot values of a proportional gadget are "Intuition friendly" numbers, in that they represent 
concepts convenient to Intuition, and not to the application. The application must translate these numbers to 
internal values before acting on them. 

Functions for Using a Scroller 

/* 

** FindScrollerValues ( ) 

* * 

** Function to calculate the Body and Pot values of a proportional gadget 
** given the three values total, displayable, and top, representing the 
** total number of items in a list, the number of items displayable at one 
** time, and the top item to be displayed. For example, a file requester 
** may be able to display 10 entries at a time. The directory has 20 



** entries in it, and the top one displayed is number 3 (the fourth one, 
** counting from zero) , then total - 20, displayable = 10, and top = 3. 
* * 

** Note that this routine assumes that the displayable variable is greater 
** than the overlap variable. 

** A final value, overlap, is used to determine the number of lines of 

** "overlap" between pages. This is the number of lines displayed from the 

** previous page when jumping to the next page. 

*/ 

void FindScrollerValues (UWORD total, UWORD displayable, UWORD top, 
WORD overlap, UWORD *body, UWORD *pot) 

{ 

UWORD hidden; 

/* Find the number of unseen lines: */ 
hidden = max (total - displayable, 0) ; 

/* If top is so great that the remainder of the list won't even 

** fill the displayable area, reduce top: 

*/ 

if (top > hidden) 

top = hidden; 

/* body is the relative size of the proportional gadget's knob. Its size 
** in the container represents the fraction of the total that is in view. 
** If there are no lines hidden, then body should be full-size (MAXBODY) . 
** Otherwise, body should be the fraction of (the number of displayed 
** lines - overlap) / (the total number of lines - overlap) . The "- overlap" 

144 Amiga ROM Kernel Reference Manual: Libraries 

** is so that when the user scrolls by cloaking in the container of the 

** scroll gadget, then there is some overlap between the two views. 

*/ 

(*body) = (hidden > 0) ? 

(UWORD) ( ( (ULONG) (displayable - overlap) * MAXBODY) / (total - overlap) ) 

MAXBODY ; 

/* pot is the position of the proportional gadget knob, with zero meaning that 

** the scroll gadget is all the way up (or left) , and full (MAXPOT) meaning 

** that the scroll gadget is all the way down (or right) . If we can see all 

** the lines, pot should be zero. Otherwise, pot is the top displayed line 

** divided by the number of unseen lines. 

*/ 

(*pot) = (hidden > 0) ? (UWORD) (((ULONG) top * MAXPOT) / hidden) : ; 

/* 

** FindScrollerTop ( ) 

** Function to calculate the top line that is displayed in a proportional 

** gadget, given the total number of items in the list and the number 

** displayable, as well as the HorlzPot or VertPot value. 

*/ 

UWORD FindScrollerTop (UWORD total, UWORD displayable, UWORD pot) 

{ 

UWORD top, hidden; 

/* Find the number of unseen lines. */ 
hidden = max (total - displayable, 0) ; 

/* pot can be thought of as the fraction of the hidden lines that are before 



** the displayed part of the list, in other words a pot of zero means all 
** hidden lines are after the displayed part of the list (i.e. top = 0) , 
** and a pot of MAXPOT means all the hidden lines are before the displayed 
** part (i.e. top = hidden) . 

* * 

** MAXPOT/2 is added to round up values more than half way to the next position. 

*/ 

top = ( ( (ULONG) hidden * pot) + (MAXPOT/2)) >> 16; 

/* Once you get back the new value of top, only redraw your list if top 
** changed from its previous value. The proportional gadget may not have 
** moved far enough to change the value of top. 
return (top) ; 
} 

Functions for Using a Slider 

/* 

** FindSliderValues ( ) 

* * 

** Function to calculate the Body and Pot values of a slider gadget given the 

** two values numlevels and level, representing the number of levels available 

** in the slider, and the current level. For example, a Red, Green, or Blue 

** slider would have (currently) numlevels = 16, level = the color level (0-15) . 

*/ 

void FindSliderValues (UWORD numlevels, UWORD level, UWORD *body, UWORD *pot) 

{ 

/* body is the relative size of the proportional gadget's body. 

** Clearly, this proportion should be 1 / numlevels. 

*/ 

if (numlevels > 0) 

(*body) = (MAXBODY) / numlevels; 
else 

(*body) = MAXBODY; 

/* pot is the position of the proportional gadget body, with zero meaning that 
** the slider is all the way up (or left) , and full (MAXPOT) meaning that the 
** slider is all the way down (or right) . 

** For slider gadgets the derivation is a bit ugly: 
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** We illustrate a slider of four levels (0, 1, 2, 3) with the slider at 

** level 2. The key observation is that pot refers the the leading edge of 

** the knob and as such MAXPOT is not all the way to the right, but is one 

** bodying width left of that. 

* * 

** Level: 12 3 

** 

** j I 1******1 
** j j 1******1 
** I | 1******1 
** I i 1******1 
** 

I I 

** pot MAXPOT 

* * 

** From which we observe that pot - MAXPOT * (level/ (numlevels-1) ) 
*/ 



if (numlevels > 1) 

(*pot) = ( ( (ULONG)MAXPOT) * level) / (numlevels-1) ; 



else 



(*pot) - 0; 



/* 

** FindSliderLevel ( ) 

** Function to calculate the level of a slider gadget given the total number 

** of levels as well as the HorizPot or VertPot value. 

*/ 

UWORD FindSliderLevel (UWORD numlevels, UWORD pot) 

{ 

UWORD level; 

/* We illustrate a 4 -level slider (0 , 1, 2 , 3) with the knob on the transition 
** point between calling it at levels 1 and 2 . 

* * 

** Level: 12 3 

** 

* * i j * * I ** I I 

* * j j * * I ** j j 

* * j I * * I ** I j 

* * j I * * I ** j j 
** 

l l 

** pot MAXPOT 

** We've already shown that the vertical lines (which represent the natural 
** position of the knob for a given level are: 

* * 

** pot = MAXPOT * (level/ (numlevels-1) ) 

* * 

** and we see that the threshold between level and level -1 is half-way between 
** pot (level) and pot (level-1) , from which we get 

** level = (numlevels-1) * (pot /MAXPOT) + 1/2 
*/ 

if (numlevels > 1) 

{ 

level = ( ( (ULONG)pot) * (numlevels-1) + MAXPOT/2) / MAXPOT; 

} 
else 

{ 

level = 0; 

} 
return (level) ; 

} 
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INITIALIZATION OF A PROPORTIONAL GADGET 

The proportional gadget is initialized like any other gadget, with the addition of the Proplnfo structure. 



Initialization of the Proplnfo Structure 

This is the special data required by the proportional gadget. 

struct Proplnfo 

{ 

UWORD Flags; 

UWORD HorizPot; 

UWORD VertPot; 

UWORD HorizBody; 

UWORD VertBody; 

UWORD Cwidth; 

UWORD Cheight; 

UWORD HPotRes, VPotRes; 

UWORD LeftBorder; 

UWORD TopBorder; 

}; 

Flags 

In the Flags variable, the following flag bits are of interest: 

PROPBORDERLESS 

Set the PROPBORDERLESS flag to create a proportional gadget without a border. 

AUTOKNOB 

Set the AUTOKNOB flag in the Flags field to use the auto-knob, otherwise the application 
must provide knob imagery. 

FREEHORIZ and FREEVERT 

Set the FREEHORIZ flag to create a gadget that adjust left-to-right, set the FREEVERT flag 
for top-to-bottom movement. Both flags may be set in a single gadget. 

PROPNEWLOOK 

Set the PROPNEWLOOK flag to create a gadget with the new look. If this flag is not set, the 
gadget will be rendered using a V34 compatible design. 

KNOBHIT 

The KNOBHIT flag is set by Intuition when this knob is hit by the user. 

HorizPot and VertPot 

Initialize the HorizPot and VertPot variables to their starting values before the gadget is added to the 
system. The variables may be read by the application. The gadget must be removed before writing to 
these variables, or they may be modified with NewModifyProp(). 

HorizBody and VertBody 

Set the HorizBody and VertBody variables to the desired increment. If there is no data to show or 
the total amount displayed is less than the area in which to display it, set the body variables to the 
maximum, MAXBODY. 

The remaining variables and Flags are reserved for use by intuition. 
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Initialization of the Gadget Structure 

In the Gadget structure, set the GadgetType field to GTYP_PROPGADGET and place the address of the 
Proplnfo structure in the Speciallnfo field. 

When using AUTOKNOB, the GadgetRender field must point to an Image structure. The Image need not be 
initialized when using AUTOKNOB, but the structure must be provided. These Image structures may not be 
shared between gadgets, each must have its own. 



To use application imagery for the knob, set GadgetRender to point to an initialized Image structure. If the 
knob highlighting is done by alternate image (GFLG_GADGHIMAGE), the alternate image must be the same 
size and type as the normal knob image. 

MODIFYING AN EXISTING PROPORTIONAL GADGET 

To change the flags and the pot and body variables after the gadget is displayed, the program can call 
NewModifyProp(). 

void NewModifyProp ( struct Gadget *gadget, struct Window *window, struct Requester ^requester, 

unsigned long flags, unsigned long horizPot, unsigned long vertPot, 
unsigned long horizBody, unsigned long vertBody, long numGad ) ; 

The gadget's internal state will be recalculated and the imagery will be redisplayed to show the new state. 
When numGads (in the prototype above) is set to all ones, NewModifyProp() will only update those parts of 
the imagery that have changed, which is much faster than removing the gadget, changing values, adding the 
gadget back and refreshing its imagery. 



String Gadget Type 



A string gadget is an area of the display in which a single field of character data may be entered. When a 
string gadget is activated, either by the user or by the application, a cursor appears prompting the user to 
enter some text. Any characters typed will be placed into the active string gadget, unless the gadget is 
deactivated by other mouse activity or program interaction. 

In Release 2, the system also supports tabbing between a group of string gadgets. In this mode, pressing the 
tab key will advance the active gadget to the next string gadget and pressing shifted tab will advance to the 
previous string gadget. 

Control characters are generally filtered out, but may be entered by pressing the Left Amiga key with the 
desired control character. The filtering may be disabled by the program, or by the user via the IControl 
Preferences editor. 

String gadgets feature auto-insert, which allows the user to insert characters wherever the cursor is. Overwrite 
mode is also available, and the application may toggle the gadget between the two modes. 

When the user activates a string gadget with the mouse, the gadget's cursor moves to the position of the 
mouse. The user may change the position of the cursor both with the cursor keys and with the mouse pointer. 
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A number of simple, keyboard driven editing functions are available to the user. These editing functions are 
shown in the following table. 



Table 5-1 : Editing Keys and Their Functions 



Key 



Function 

Cursor to previous character. 

Cursor to beginning of string. 

Cursor to next character. 

Cursor to end of string. 

Delete the character under the cursor. Does nothing in fixed field 

mode. 

Delete from the character under the cursor to the end of the line. Does 

nothing in fixed field mode. 

Delete the character to left of cursor. In fixed field mode, move cursor 

to previous character. 

Delete from the character to the left of the cursor to the start of the line. 

In fixed field mode, move cursor to beginning of string. 

Terminate input and deactivate the gadget. If the GACT_RELVERIFY 

activation flag is set, the program will receive a IDCMP_GADGETUP 

event for this gadget. 

Undo (cancel) the last editing change to the string. 

Clears the input buffer. The undo buffer is left undisturbed. In fixed 

field mode, move cursor to beginning of string. 



<- 

Shift <- 
-> 

Shift -> 
Del 

Shift Del 

Backspace 

Shift Backspace 

Return or Enter 



Right Amiga Q 
Right Amiga X 



The following additional editing functions are available only when "Filter Control Characters" is on for the string 
gadget. Control character filtering is only available if the IControl preferences editor has "Text Gadget Filter" 
selected and the individual gadget does not have SGM_NOFILTER set. 

Table 5-2: Additional Editing Keys and Their Functions 



Key 



Ctrl A 
CtrlH 

CtrIK 

CtrIM 
CtrlW 

CtrlU 

CtrIX 

CtrIZ 



Function 



Jump cursor to start of buffer. 

Delete the character to the left of the cursor. In fixed field mode, move 

cursor to previous character. 

Delete from the character under the cursor to the end of the string. 

Does nothing in fixed field mode. 

Equivalent to Return or Enter (end gadget). 

Delete the previous word. In fixed field mode, jump cursor to the start 

of the previous word. 

Delete from the character to the left of the cursor to the start of the 

buffer. In fixed field mode, jump cursor to the start of the buffer. 

Clears the input buffer (like Right Amiga X). In fixed field mode, jump 

cursor to the start of the buffer. 

Jump cursor to end of buffer. 
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INTEGER GADGET TYPE 



The integer gadget is really a special case of the string gadget type. Initialize the gadget as a string gadget, 
then set the GACT_LONGINT flag in the gadget's Activation field. 

The user interacts with an integer gadget using exactly the same rules as for a string gadget, but Intuition 
filters the input, allows the user to enter only a plus or minus sign and digits. The integer gadget returns a 
signed 32-bit integer in the Stringlnfo variable Longlnt. 

To initialize an integer gadget to a value, preload the input buffer with an ASCII representation of the initial 
integer. It is not sufficient to initialize the gadget by merely setting a value in the Longlnt variable. 



Integer gadgets have the Longlnt value updated whenever the ASCII contents of the gadget changes, and 
again when the gadget is deactivated. 

STRING GADGET IDCMP MESSAGES 

If the application has specified the GACT_RELVERIFY activation flag, it will be sent an IDCMP_GADGETUP 
message when the gadget is properly deactivated. This happens when Return or Enter is pressed, when 
tabbing to the next string gadget (where supported), and when a custom string editing hook returns 
SGA_END. 

The gadget may become inactive without the application receiving an IDCMP_GADGETUP message. This will 
happen if the user performs some other operation with the mouse or if another window is activated. The 
gadget may still contain updated, valid information even though the IDCMP_GADGETUP message was not 
received. 

PROGRAM CONTROL OF STRING GADGETS 

ActivateGadget() allows the program to activate a string gadget (and certain custom gadgets). If successful, 
this function has the same effect as the user clicking the mouse select button when the mouse pointer is within 
the gadget's select box and any subsequent keystrokes will effect the gadget's string. 

BOOL ActivateGadget( struct Gadget *gadget, struct Window *window, struct Requester ""requester ); 

This function will fail if the user is in the middle of some other interaction, such as menu or proportional gadget 
operation. In that case it returns FALSE, otherwise it returns TRUE. The window or requester containing the 
string gadget to be activated must itself be open and active. Since some operations Intuition may occur after 
the function that initiates them completes, calling ActivateGadgetQ after OpenWindowTagListQ or 
RequestQ is no guarantee that the gadget will actually activate. Instead, call ActivateGadget() only after 
having received an IDCMP_ACTIVEWINDOW or IDCMP_REQSET message for a newly opened window or 
requester, respectively. 

The Window Active Message Is Required. It is incorrect to simply insert a small delay 
between the call to OpenWindowTagList( ) or RequestQ and the call to 
ActivateGadgetQ. Such schemes fail under various conditions, including changes in 
processor speed and CPU loading. 
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If you want to activate a string gadget in a newly opened window that has a shared IDCMP UserPort, there is 
an additional complication. Sharing UserPorts means that the window is opened without any IDCMP 
messages enabled, and only later is ModifylDCMP() called to turn on message passing. If the newly opened 
window becomes active before ModifylDCMP() is called, the IDCMP_ACTIVEWINDOW message will not be 
received (because IDCMP message passing was off at the time). The following code will handle this problem: 

BOOL activated; 

/* Open window with NULL IDCMPFlags */ 
win = OpenWlndow ( ... ) ; 

/* Set the UserPort to your shared port, and turn on message passing, 

* which includes the IDCMP_ACTIVEWINDOW message. 
*/ 

wln->UserPort = sharedport; 
ModifyIDCMP( win, ... | IDCMP_ACTI VEWINDOW | ... ) ; 

/* If the window became active before the ModlfylDCMP ( ) got executed 

* then this ActivateGadget ( ) can succeed. If not, then this 

* ActivateGadget ( ) might be too early, but in that case, we know 

* we'll receive the IDCMP_ACTIVEWINDOW event. We handle that below. 

*/ 

activated = ActivateGadget ( stringgad, win, NULL ) ; 



and later, in the event loop: 

if ( (msg->Class == ACTIVEWINDOW) && ( ! activated ) ) 
success = ActivateGadget (stringgad . . . ) ; 

Note however that a window which has the WA_Activate attribute is not guaranteed to be activated upon 
opening. Certain conditions (like an active string gadget in another window) will prevent the automatic initial 
activation of the window. Therefore, do not let your code depend on receiving the initial 
IDCMP_ACTIVEWINDOW message. 

String Gadget Example 

The values of a string gadget may be updated by removing the gadget, modifying the information in the 
Stringlnfo structure, adding the gadget back and refreshing its imagery. 

;/* updatestrgad. c - Execute me to compile me with SAS C 5.10 

LC -bl -cfistq -v -y -J73 updatestrgad. c 

Blink FROM LIB : c . o, updatestrgad. o TO updatestrgad LIBRARY 

LIB :LC. lib, LIB: Amiga. lib 

quit 

** The values of a string gadget may be updated by removing the gadget, 
** modifying the information in the Stringlnfo structure, adding the 
** gadget back and refreshing its imagery. 
* * 

** updatestrgad. c - Show the use of a string gadget. Shows both the use 

** of ActivateGadget ( ) and how to properly modify the contents of a string 

** gadget. 

*/ " 

ttdefine INTUI_V3 6_NAMES_ONLY 

#include <exec/types . h> 
#include <intuition/intuition.h> 
#include <intuition/intuitionbase .h> 

#include <clib/exec_protos . h> 
#include <clib/dos_protos .h> 
#include <clib/intuition_protos .h> 

#include <string.h> 
#include <stdio.h> 



#ifdef LATTICE 
int CXBRK(void) 
int chkabort (void) 
#endif 



return(O) ; } /* Disable Lattice CTRL/C handling */ 
return (0) ; } /* really */ 



/* our function prototypes */ 

VOID updateStrGad (struct Window *win, struct Gadget *gad, 

VOID handleWindow (struct Window *win, struct Gadget *gad) 



UBYTE *newstr) 



struct Library *IntuitionBase; 

/* NOTE that the use of constant size and positioning values are 

** not recommended; it just makes it easy to show what is going on. 

** The position of the gadget should be dynamically adjusted depending 

** on the height of the font in the title bar of the window. This 

** example adapts the gadget height to the screen font. Alternately, 

** you could specify your font under V37 with the StringExtend structure. 

*/ 

#define BUFSIZE (100) 



#define MYSTRGADWIDTH (200) 
#define MYSTRGADHEIGHT (8) 

UWORD strBorderData [] = 

{ 

0,0, MYSTRGADWIDTH + 3,0, MYSTRGADWIDTH + 3 , MYSTRGADHEIGHT + 3, 

0, MYSTRGADHEIGHT + 3, 0,0, 

}; 

struct Border strBorder = 

{ 

-2,-2,1, 0, JAM1, 5, StrBorderData, NULL, 

}; 

UBYTE strBuffer [BUFSIZE] ; 
UBYTE StrUndoBuffer [BUFSIZE] ; 
struct Stringlnfo strlnfo = 

{ 

strBuffer, strUndoBuffer, 0, BUFSIZE, /* compiler sets remaining fields to zero 

*/ 

}; 

struct Gadget strGad = 

{ 

NULL, 20 , 20, MYSTRGADWIDTH, MYSTRGADHEIGHT, 
GFLG_GADGHCOMP , GACT_RELVERIFY | GACT_STRINGCENTER, 
GTYP_STRGADGET, kstrBorder, NULL, NULL, , &str Info, , NULL, 

}; 

#define ANSCNT 4 

UBYTE *answers [ANSCNT] = {"Try again" , "Sorry" ," Perhaps" , "A Winner"}; 

int ansnum = ; 

UBYTE *activated_txt = "Activated"; 

/* main - show the use of a string gadget. 

*/ 

VOID main (int argc, char **argv) 

{ 

struct Window *win; 

/* make sure to get intuition version 37, for OpenWindowTags ( ) */ 
IntuitionBase = OpenLibrary ( "intuition. library" , 37); 
if (IntuitionBase) 

{ 

/* Load a value into the string gadget buffer. 

** This will be displayed when the gadget is first created. 

*/ 

strcpy (strBuffer, "START"); 

if (win = OpenWindowTags (NULL, 

WA_Width, 4 00, 

WA_Height, 10 0, 

WA_Title, "Activate Window, Enter Text", 

WA_Gadgets, &strGad, 

WA_CloseGadget , TRUE, 

WA_IDCMP, IDCMP_ACTIVEWINDOW | 

IDCMP_CLOSEWINDOW | IDCMP_GADGETUP, 
TAG_END) ) 

{ 

handleWindow (win, &strGad) ; 

CloseWindow (win) ; 

} 
CloseLibrary (IntuitionBase) ; 



} 

/* 

** Process messages received by the window. Quit when the close gadget 

** is selected, activate the gadget when the window becomes active. 

*/ 

VOID handleWindow (struct Window *win, struct Gadget *gad) 

{ 

struct IntuiMessage *msg; 
struct Gadget *gadget; 
ULONG class; 

for (;;) 

{ 

Wait(lL << win->UserPort->mp_SigBit) ; 

while (msg = (struct IntuiMessage *) GetMsg (win->UserPort) ) 

{ 

/* Stash message contents and reply, important when message 
** triggers some lengthy processing 
*/ 

class = msg->Class; 
/* If it's a gadget message, IAddress points to Gadget */ 
if ((class == IDCMP_GADGETUP) | | (class == IDCMP_GADGETDOWN) ) 

gadget = (struct Gadget *) msg- > IAddress ; 
ReplyMsg ( (struct Message *)msg); 

switch (class) 

{ 

case IDCMP_ACTIVEWINDOW: 

/* activate the string gadget. This is how to activate a 

** string gadget in a new window- -wait for the window to 

** become active by waiting for the IDCMP_ACTIVEWINDOW 

** event, then activate the gadget. Here we report on 

** the success or failure. 

*/ 

if (ActivateGadget (gad, win, NULL) ) 

updateStrGad (win, gad, activated_txt) ; 

break; 
case IDCMP_CLOSEWINDOW : 

/* here is the way out of the loop and the routine. 

** be sure that the message was replied. . . 

*/ 

return; 

break; 
case IDCMP_GADGETUP : 

/* If user hit RETURN in our string gadget for demonstration, 

** we will change what he entered. We only have 1 gadget, 

** so we don't have to check which gadget. 

*/ 

updateStrGad (win, &strGad, answers [ansnum] ) ; 
if (++ansnum > ANSCNT) ansnum = 0; /* point to next answer */ 

break; 
} 
} 
} 
} 

/* 

** Routine to update the value in the string gadget's buffer, then 

** activate the gadget. 

*/ 

VOID updateStrGad (struct Window *win, struct Gadget *gad, UBYTE *newstr) 



{ 

/* first, remove the gadget from the window. this must be done before 

** modifying any part of the gadget! ! ! 

*/ 

RemoveGList (win, gad, 1) ; 

/* For fun, change the value in the buffer, as well as the cursor and 

** initial display position. 

*/ 

strcpy (( (struct Stringlnfo *) (gad->SpecialInfo) ) ->Buf f er, newstr) ; 

((struct Stringlnfo *) (gad->SpecialInf o) ) ->Buf f erPos = 0; 

((struct Stringlnfo *) (gad->SpecialInf o) ) ->DispPos = ; 

/* Add the gadget back, placing it at the end of the list (~0) 

** and refresh its imagery. 

*/ 

AddGList (win, gad, ~0, 1,NULL) ; 

RefreshGList (gad, win, NULL, 1) ; 

/* Activate the string gadget */ 
ActivateGadget (gad, win, NULL) ; 
} 

TABBING BETWEEN STRING GADGETS 

The Amiga allows tabbing to the next string gadget in a window or requester and shifted tabbing to the 
previous string gadget. This function operates starting with V37. 

If the GFLG_TABCYCLE flag is set, this string participates in cycling activation with Tab or Shift Tab. If only a 
single gadget has this flag set, then the Tab keys will have no effect. If one of the Tab keys is pressed while in 
a string gadget without GFLG_TABCYCLE set, nothing will happen, even though other string gadgets may 
have the flag set. 

Activation order is determined by the order of the string gadgets in the gadget list, following the NextGadget 
link. The tab key will advance to the next string gadget with GFLG_TABCYCLE set, shifted tab will move to 
the previous gadget. To order gadgets for tabbing (next previous string gadget), place them in the correct 
order in the gadget list when they are added to the system. This order must be maintained if the gadgets are 
removed and put back, or the tabbing order will change. 

The tab keys will de-activate the current gadget as if one of the Return or Enter keys had been pressed, 
sending an IDCMP_GADGETUP message to the application. The application can recognize that tab was 
pressed by looking for 0x09 (the ASCII tab character) in the Code field of the IDCMP_GADGETUP 
IntuiMessage. If necessary, it can then inspect the qualifier field of that message to see if the shift key was 
pressed. The next string gadget with GFLG_TABCYCLE set will be activated, with shifted tab activating the 
previous string gadget. 

GADGET STRUCTURE FOR STRING GADGETS 

To an application, a string gadget consists of a standard Gadget structure along with an entry buffer, an undo 
buffer and a number of extensions. 

For a string gadget, set the GadgetType field in the Gadget structure to GTYP_STRGADGET. Set the 
Speciallnfo field to point to an instance of a Stringlnfo structure, which must be initialized by the application. 

The container for a string gadget is its select box. The application specifies the size of the container. As the 
user types into the string gadget, the characters appear in the gadget's container. 

String gadgets may hold more characters than are displayable in the container. To use this feature, the 
application simply provides a buffer that is larger than the number of characters that will fit in the container. 
This allows the user to enter and edit strings that are much longer than the visible portion of the buffer. 
Intuition maintains the cursor position and scrolls the text in the container as needed. 



The application may specify the justification of the string in the container. The default is GACT_STRINGLEFT, 
or left justification. If the flag GACT_STRINGCENTER is set, the text is center justified; if 
GACT_STRINGRIGHT is set, the text is right justified. 
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When a gadget is activated, the select box contents are redrawn, including the background area. If 
GFLG_STRINGEXTEND is set for the gadget or the gadget is using a proportional font by default, then the 
entire select box will be cleared regardless of the font size or Stringlnfo.MaxChars value. For compatibility 
reasons, if the string gadget is not extended then the following conditions apply (see the section on "Extending 
String Gadgets" for more information). 

If the font is monospace (not proportional), the width of the gadget will be rounded down to an even 
multiple of the font width. 

If the string gadget is left justified (GACTSTRINGLEFT), a maximum of Stringlnfo.MaxChars times 
the font width pixels of space will be- cleared. Thus, if MaxChars is 3 (two characters plus the trailing 
NULL) and the font width is 8, then a maximum of 3 * 8 = 24 pixels will be cleared. If the font defaults 
to a proportional font, then the width resumed by FontExtent() will be used as the character width. 

No facilities are provided to place imagery within the select box of a string gadget. 

String Gadget Imagery and Highlighting 

Any type of image may be supplied for the rendering of a string gadget-image, border, or no image at all. The 
highlighting for a string gadget must be the complementing type (GFLG_GADGHCOMP). Alternate imagery 
may not be used for highlighting. 

STRINGINFO STRUCTURE 

String gadgets require their own special structure called the Stringlnfo structure. 

struct Stringlnfo 

{ 

UBYTE * Buffer; 
UBYTE *UndoBuf fer; 
WORD BufferPos; 
WORD MaxChars; 
WORD DlspPos; 
WORD UndoPos, 
WORD NumChars; 
WORD DispCount; 
WORD CLeft, Ctop; 

struct StringExtend *Extension, 
LONG Longlnt, 
struct KeyMap *AltKeyMap; 

}; 

Buffer 

The application must supply an input buffer (Buffer) and an optional undo buffer (UndoBuffer) for 
the gadget. The input buffer is where data typed into the gadget is placed by Intuition. The program 
can examine this buffer at any time. 

A string copied into the input buffer before the gadget is added to the system will be displayed in the 
gadget when it is displayed, and may then be edited by the user. The input buffer may be initialized 
to any starting value, as long as the initial string is NULL terminated and fits within the buffer. To 
initialize the buffer to the empty string (no characters), put a NULL in the first position of the buffer. 

Integer gadgets must have the ASCII value of the initial number placed into the Buffer before the H 
i gadget is added to the system. 
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UndoBuffer 

If a string gadget has an undo buffer, the undo feature will be enabled. "Undo" allows the user torever 
to the initial string (the value in the buffer before gadget activation) at any time before the gadget 
becomes inactive. The UndoBuffer is used to hold a copy of the previous string while the user edits 
the current string. When the gadget is activated, the Buffer is copied to the UndoBuffer. The Buffer 
may be restored at any time up to the time the gadget is deactivated, by typing right-Amiga Q. 

Multiple string gadgets may share the same undo buffer as long as the buffer is as large as the 
largest input buffer. 

MaxChars 

MaxChars tells Intuition the size of the input buffer. This count includes the trailing NULL of any data 
entered into the buffer, so the number of characters the gadget may hold is MaxChars - 1 . 

BufferPos 

BufferPos is initialized to the current position of the cursor in the buffer. BufferPos runs from zero to 
one less than the length of the string. If this position is not within the characters that will be displayed, 
Intuition will adjust DispPos for the gadget to make the cursor visible. 

DispPos 

DispPos is initialized to the starting character in the string to display on screen. This allows strings 
longer than the number of displayable characters to be positioned within the gadget. Intuition will not 
position the string such that there is empty character space to the right of the string and characters 
scrolled out of the gadget box to the left. 

UndoPos, NumChars, DispCount, CLeft and CTop 

These variables are maintained by Intuition and should not be modified by the application. UndoPos 
specifies the character position in the undo buffer. NumChars specifies the number of characters 
currently in the buffer. DispCount specifies the number of whole characters visible in the container. 

Extension 

The Stringlnfo Extension allows for additional control over string gadget behaviour and 
appearance. See below for details. 

Longlnt 

Longlnt contains the integer value entered into an Integer type of string gadget. After the user has 
finished entering an integer, the application can read the value in this variable. 

Gadget Key Mapping 

By default, screen characters appear using simple ASCII key translations. If desired, the application can set 
up alternate key mapping. A pointer to the KeyMap structure is placed into the AltKeyMap field of the 
Stringlnfo structure. The GACTALTKEYMAP bit in the Activation flags of the gadget must also be set. 

See the "Console Device" chapter in the Amiga ROM Kernel Reference Manual: Devices, and the "Keymap 
Library" chapter in this manual for more information about the console device and key mapping. 
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EXTENDED STRING GADGETS 

The Stringlnfo structure may be extended by setting the GFLG_STRINGEXTEND gadget flag and placing a 
pointer to a StringExtend structure in the Stringlnfo Extension variable. GFLG_STRINGEXTEND is 
available beginning with V37, under V36 the application must use GACT_STRINGEXTEND to get the same 
functionality. Note that GACT_STRINGEXTEND is not ignored prior to V36 and should only be set in V36 or 
later systems. GFLG_STRINGEXTEND is ignored prior to V37. 



struct StringExtend 

{ 

struct TextFont *Font; 
UBYTE Pens [2] ; 
UBYTE ActivePens [2] ; 
ULONG InitialModes; 
struct Hook *EditHook; 
UBYTE *WorkBuf fer; 
ULONG Reserved [4] ; 

}; 

Font 

If a font is specified in the StringExtend structure, that font will be used by the gadget. By default, 
the string gadget inherits the font of the screen on which it appears. Note that this is a pointer to an 
open font and not a pointer to a TextAttr structure. 

Proportional fonts are supported in string gadgets starting with Release 2. If the select box of the 
gadget is not tall enough to render the font, Intuition will fall back to topaz 8. 

Pens 

Pens specify the pens used to render the text while the gadget is inactive. Pens[0] is the foreground 
(text) pen, Pens[1] is the background pen. 

ActivePens 

ActivePens specify the pens used to render the text while the gadget is active. ActivePens[0] is the 
foreground (text) pen, ActivePens[1] is the background pen. 

InitialModes 

These modes may be used in StringExtend structure InitialModes field. 

SGM_REPLACE 

If this flag is set, the string gadget will be in replace or overwrite mode. If this flag is cleared, the 
string gadget will be in insert mode. In replace mode, characters entered overwrite the existing 
characters. In insert mode, characters entered are inserted into the buffer and the following 
characters are advanced by one position until the buffer is full. If the buffer is full in insert mode then 
characters may not be entered until some are deleted. 

When using this flag, always initialize Stringlnfo with an in-range value of BufferPos. While most 
changes to gadgets require the application to first remove the gadget before modifying the gadget, 
this flag may be toggled without removing the gadget from the gadget list. The change will take effect 
on the next character typed by the user. 
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SGM_NOFILTER 

Don't filter control chars, enter them into the gadget as typed. In this mode the control character 
command keys for string gadgets are not active. If the user disables control character filtering from 
the IControl Preferences editor, there is no way for the application to turn it on for an individual string 
gadget. In filter mode, control characters may be entered into the string by holding the left Amiga key 
while the character is entered. 

While most changes to gadgets require the application to first remove the gadget before modifying 
the gadget, this flag may be toggled without removing the gadget from the gadget list. The change 
will take effect on the next character typed by the user. 

SGM_FIXEDFIELD 

Fixed length buffer used for editing, the user cannot shorten or lengthen the string through edit 
operations. The field length is taken from the length of the character string in the buffer when the 
gadget is added to the system. Fixed field mode modifies the meanings of many of the string editing 
keys, as explained in the tables above. Always set SGM_REPLACE when using a fixed length buffer. 



SGM_EXITHELP 

Allows the help key to be heard by the application from within string gadgets. The gadget will exit 
immediately when the help key is pressed with the IntuiMessage.Code set to Ox5F (new for V37). 

EditHook and WorkBuffer 

EditHook and WorkBuffer are used for custom string editing, which is discussed below. 

CUSTOM STRING EDITING 

The application may choose to control the editing features provided in string gadgets used within the 
application. To locally install the custom string editing features, the application provides a hook in the 
StringExtend structure EditHook field. 

A hook is a well defined calling interface for a user provided subroutine or function. Hooks are more fully 
described in the "Utility Library" chapter. A string gadget hook is called in the standard way, where the hook 
object is a pointer to a SGWork structure, and the hook message is a pointer to a command block. However, 
unlike a function callback hook, a string gadget editing hook is called on Intuition's task context, not on the 
application's own context. Therefore, a string gadget editing hook must not use dos. library, and may not 
Wait() on application signals or message ports, and may not call any Intuition function which might wait for 
Intuition. 

The command block starts with either (longword) SGH_KEY or SGH_CLICK. There may be new commands 
added in the future, so the application should not assume that these are the only possible commands. The 
hook should return zero if it doesn't understand the command and non-zero if the command is supported. 

The SGWork structure, defined in <intuition/sghooks.h>, is listed on the next page. Use this structure as the 
hook object for custom string editing hooks. 
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SGWork Structure 

struct SGWork 

{ 

struct Gadget * Gadget ; 

struct Stringlnfo *StringInfo; 

UBYTE *WorkBuf fer; 

UBYTE * PrevBuffer; 

ULONG Modes; 

struct InputEvent Prevent; 

UWORD Code ; 

WORD BufferPos; 

WORD NumChars ; 

ULONG Actions 

LONG LongInt_ 

struct Gadgetlnfo *GadgetInfo; 

UWORD EditOp; 

}; 

The local (application) hook may only change the Code, Actions, WorkBuffer, NumChars, BufferPos and 

Longlnt fields. None of the other fields in the SGWork structure may be modified. 

Gadget and Stringlnfo 

The values in the string gadget before any modification are available through the Gadget and 
Stringlnfo pointers. 

PrevBuffer 

The PrevBuffer provides a shortcut to the old, unmodified string buffer. 

WorkBuffer, BufferPos, NumChars and Longlnt 



I Event 



Code 



WorkBuffer, BufferPos, NumChars and Longlnt contain the values that the string gadget will take 
if the edits are accepted. If the edit hook updates these values, the gadget will take on the updated 
values. 



lEvent contains the input event that caused this call to the hook. This input event is not keymapped. 
Only use this event for action keys, like the Return key, function keys or the Esc key. 



If the input event maps to a single character, the keymapped value will be in the Code field. The 
Code field may also be modified, and the value placed in it will be passed back to the application in 
the IDCMP_GADGETUP message when SGA_END is specified in the Actions field. 

Gadgetlnfo 

A structure of information defined in <intuition/cghooks.h>. This structure is read only. See the 
"BOOPSI" chapter for more information. 



Modes 



The modes of the gadget such as insert mode, defined below. 



Actions 



The action taken by the edit hook, defined below. 

EditOp 

The type of edit operation done by the global hook, defined below. 
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EditOp Definitions 

These values indicate the basic type of operation the global editing hook has performed on the string before 
the application gadget's custom editing hook gets called. Only global editing hooks must update the value in 
the EditOp field before they return. The value placed in the field should reflect the action taken. 



EditOp 


Action Taken bv Global Hook 


EO NOOP 


Did nothing. 


EO DELBACKWARD 


Deleted some chars (possibly 0). 


EO DELFORWARD 


Deleted some characters under and in front of the cursor. 


EO MOVECURSOR 


Moved the cursor. 


EO ENTER 


Enter or Return key, terminate. 


EO RESET 


Current Intuition-style undo. 


EO REPLACECHAR 


Replaced one character and (maybe) advanced cursor. 


EO INSERTCHAR 


Inserted one character into string or added one at end. 


EO_BADFORMAT 


Didn't like the text data, e.g., alpha characters in a 




GACTJ-ONGINT type. 


EO BIGCHANGE 


Complete or major change to the text, e.g. new string. 


EO UNDO 


Some other style of undo. 


EO CLEAR 


Clear the string. 


EO SPECIAL 


An operation that doesn't fit into the categories here. 



Actions Definitions 

These are the actions to be taken by Intuition after the hook returns. Set or clear these bits in SGWork 
structure Actions field. A number of these flags may already be set when the hook is called. 



Actions Flag 


Purpose 


SGA USE 


If set, use contents of SGWork. 


SGA END 


Terminate gadget, Code field is sent to application in 




IDCMP GADGETUP event code field. 


SGA BEEP 


Beep (i.e., flash) the screen. 


SGA REUSE 


Reuse the input event. Only valid with SGA_END. 


SGA REDISPLAY 


Gadget visuals have changed, update on screen. 


SGA NEXTACTIVE 


Make next possible gadget active (new for V37). 


SGA PREVACTIVE 


Make previous possible gadget active (new for V37). 



The SGH_KEY Command 

The SGH_KEY command indicates that the user has pressed a key while the gadget is active. This may be 
any key, including non-character keys such as Shift, Ctrl and Alt. Repeat keys (one call per repeat) and the 
Amiga keys also cause the hook to be called with the SGH_KEY command. The hook is not called for "key up" 
events. 

The SGH_KEY command must be supported by any custom string editing hook. There are no parameters 
following the SGH_KEY command longword. All information on the event must be derived from the SGWork 
structure. 
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Intuition processed the event and filled-in the SGWork struct before calling the hook. The information 
included in this structure includes the type of action taken (EditOp), the new cursor position (BufferPos), the 
new value in the buffer (WorkBuffer), the previous value in the buffer (PrevBuffer), the input event that 
caused this call (lEvent) and more. 

Actions with SGH_KEY 

If SGA_USE is set in the SGWork structure Actions field when the hook returns, Intuition will use the values 
in the SGWork fields WorkBuffer, NumChars, BufferPos, and Longlnt; copying the WorkBuffer to the 
Stringlnfo Buffer. SGA_USE is set by Intuition prior to calling the hook, and must be cleared by the hook if 
the changes are to be ignored. If SGAUSE is cleared when the hook returns, the stung gadget will be 
unchanged. 

If SGA_END is set when the hook returns, Intuition will deactivate the string gadget. In this case, Intuition will 
place the value found in SGWork structure Code field into the IntuiMessage.Code field of the 
IDCMPGADGETUP message it sends to the application. 

If SGA_REUSE and SGA_END are set when the hook returns, Intuition will reuse the input event after it 
deactivates the gadget. 

Starting in V37, the hook may set SGA_PREVACTIVE or SGA_NEXTACTIVE with SGA_END. This tells 
Intuition to activate the next or previous gadget that has the GFLG_TABCYCLE flag set. 

If SGA_BEEP is set when the hook returns, Intuition will call DisplayBeep(). Use this if the user has typed in 
error, or buffer is full. 

Set SGA_REDISPLAY if the changes to the gadget warrant a gadget redisplay. Changes to the cursor 
position require redisplay. 

The SGH_CLICK Command 

The SGH_CLICK command indicates that the user has clicked the select button of the mouse within the 
gadget select box. There are no parameters following the SGH_CLICK command longword. 



Intuition will have already calculated the mouse position character cell and placed that value in 
SGWork.BufferPos. The previous BufferPos value remains in the SGWork.Stringlnfo.BufferPos. 



Intuition will again use the SGWork fields listed above for SGHKEY. That is, the WorkBuffer, NumChars, 
BufferPos and Longlnt fields values may be modified by the hook and are used by Intuition if SGA_USE is 
set when the hook returns. 

Actions with SGH_CLICK 

SGA_END or SGA_REUSE may not be set for the SGH_CLICK command. Intuition will not allow gadgets 
which go inactive when chosen by the user. The gadget always consumes mouse events in its select box. 

With SGH_CLICK, always leave the SGA_REMSPLAY flag set, since Intuition uses this when activating a 
string gadget. 
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;/* strhooks.c - Execute me to compile me with SAS C 5.10 

LC -bl -cfistq -v -y -J73 strhooks.c 

Blink FROM LIB: c.o, strhooks.o TO strhooks LIBRARY LIB :LC . lib, LIB :Amiga . lib 

quit 

** strhooks.c - string gadget hooks demo 

* * 

** WARNING: This file contains "callback" functions. 

** You must disable stack checking (SAS -v flag) for them to work. 

*/ 

#define INTUI_V3 6_NAMES_ONLY 

#include <exec/types . h> 
#include <exec/memory . h> 
#include <utility/hooks . h> 
#include <devices/inputevent . h> 
#include <intuition/ intuition. h> 
#include <intuition/sghooks . h> 
#include <graphics/displayinf o . h> 

#include <clib/intuition_protos . h> 
#include <clib/utility_protos . h> 
#include <clib/exec_protos . h> 

#ifdef LATTICE 

int CXBRK(void) { return(O); } /* Disable Lattice CTRL/C handling */ 

int chkabort (void) { return(O); } /* really */ 

ttendif 

/* our function prototypes */ 

BOOL IsHexDigit (UBYTE test_char) ; 

ULONG str_hookRoutine (struct Hook *hook, struct SGWork *sgw, ULONG *msg) ; 

void initHook (struct Hook *hook, ULONG (*ccode) ( ) ) ; 

VOID handleWindow (struct Vars *vars) ; 

struct Library *IntuitionBase; 
struct Library *UtilityBase; 

#define SG_STRLEN (44) 
ttdefine MYSTRGADWIDTH (200) 
ttdefine INIT_LATER 

/* A border for the string gadget */ 

UWORD strBorderData [] = /* init elements 5 and 7 later (height adjust) */ 

{ 

0,0, MYSTRGADWIDTH + 3,0, MYSTRGADWIDTH + 3 , INIT_LATER, 

0, INIT_LATER, 0,0, 

}; 

struct Border strBorder = 



{ 

-2,-2, 1, 0, JAM1, 5, strBorderData,NULL, 

}; 

/* We'll dynamically allocate/clear most structures, buffers */ 
struct Vars 

{ 

struct Window *sgg_Window; 

struct Gadget sgg_Gadget; 

struct Stringlnfo sgg_StrInf o; 

struct StringExtend sgg_Extend; 

struct Hook sgg_Hook; 

UBYTE sgg_Buf f [SG_STRLEN] ; 

UBYTE sgg_WBuf f [SG_STRLEN] ; 

UBYTE sgg_UBuf f [SG_STRLEN] ; 

}; 

/* Main entry point. 
* * 

** Open all required libraries, set-up the string gadget. 

** Prepare the hook, open the sgg_Window and go. . . 

*/ 

VOID main(int argc, char **argv) 

{ 

struct Vars *vars ; 
struct Screen *screen; 
struct Drawlnfo *drawinfo; 

if (IntuitionBase = OpenLibrary ( "intuition. library" , 37L) ) 

{ 

if (UtilityBase = OpenLibrary ( "utility . library" , 37L) ) 

{ 

/* get the correct pens for the screen. */ 

if (screen = LockPubScreen (NULL) ) 

{ 

if (drawinfo = GetScreenDrawInfo (screen) ) 

{ 

vars = (struct Vars *) AllocMem (sizeof (struct Vars) ,MEMF_CLEAR) ; 

if (vars != NULL) 

{ 

vars- >sgg_Extend. Pens [0] = drawinf o->dri_Pens [FILLTEXTPEN] ; 
vars- >sgg_Extend. Pens [1] = drawinf o->dri_Pens [FILLPEN] ; 
vars->sgg_Extend.ActivePens [0] = 
drawinfo- >dri_Pens [FILLTEXTPEN] ; 

vars->sgg_Extend.ActivePens [1] = drawinf o->dri_Pens [FILLPEN] ; 
vars->sgg_Extend. EditHook = & (vars->sgg_Hook) ; 
vars->sgg_Extend.WorkBuf f er = vars->sgg_WBuf f ; 

vars- >sgg_StrInfo. Buff er = vars->sgg_Buf f ; 
vars->sgg_StrInf o.UndoBuf f er = vars->sgg_UBuf f ; 
vars->sgg_StrInfo.MaxChars = SG_STRLEN; 
vars->sgg_StrInfo. Extension = & (vars->sgg_Extend) ; 



gadget . 



/* There should probably be a border around the string 

** As is, it is hard to locate when disabled. 

*/ 

vars->sgg_Gadget .Lef tEdge = 2 0; 

vars->sgg_Gadget .TopEdge = 3 0; 

vars ->sgg_Gadget .Width = MYSTRGADWIDTH; 

vars- >sgg_Gadget .Height = screen- >RastPort .TxHeight ; 

vars ->sgg_Gadget. Flags = GFLG_GADGHCOMP | GFLG_STRINGEXTEND; 



vars->sgg_Gadget .Activation = 
vars->sgg_Gadget .GadgetType = 
vars->sgg_Gadget . Speciallnfo = 
vars->sgg_Gadget .GadgetRender 



GACT_RELVERI FY ; 
GTYP_STRGADGET ; 

& (vars->sgg_StrInfo) 
= (APTR) &strBorder; 



strBorderData [5] = strBorderData [7] = 
screen- >RastPort .TxHeight + 3; 

initHook (& (vars->sgg_Hook) , str_hookRoutine) 



if (vars->sgg_Window = OpenWindowTags (NULL, 



WFLG NOCAREREFRESH 



Only" , 



WA PubScreen, 


screen, 


WA_Left, 21, 


WA_Top , 2 0, 


WA_Width, 500, 


WA_Height, 15 0, 


WA_MinWidth, 50, 


WA_MaxWidth, ~0, 


WA_MinHeight, 30, 


WA_MaxHe ight , ~ , 


WA SimpleRef resh, 


TRUE, 


WA NoCareRef resh, 


TRUE, 


WA RMBTrap, 


TRUE, 


WA_IDCMP, 


IDCMP_GADGETUP IE 


WA Flags, 


WFLG_CLOSEGADGET 



WA_Title, 

WA_Gadgets, 
TAG DONE) ) 



IDCMP CLOSEWINDOW, 



WFLG_DRAGBAR | WFLG_DEPTHGADGET 

WFLG_SIMPLE_REFRESH, 

"String Hook Accepts HEX Digits 



& (vars->sgg_Gadget) , 



handleWindow (vars) ; 



CloseWindow (vars->sgg_Window) 

} 
FreeMem (vars , sizeof (struct Vars) ) 

} 
FreeScreenDrawInfo (screen, drawinfo) ; 

} 
UnlockPubScreen (NULL, screen); 

} 
CloseLibrary (UtilityBase) ; 

} 
CloseLibrary (IntuitionBase) ; 

} 



/* 

** This is an example string editing hook, which shows the basics of 
** creating a string editing function. This hook restricts entry to 
** hexadecimal digits (0-9, A-F, a-f) and converts them to upper case. 
** To demonstrate processing of mouse-clicks, this hook also detects 
** clicking on a character, and converts it to a zero. 
* * 

** NOTE: String editing hooks are called on Intuition's task context, 
** so the hook may not use DOS and may not cause Wait ( ) to be called. 
*/ 

ULONG str_hookRoutine (struct Hook *hook, struct SGWork *sgw, ULONG *msg) 

{ 

UBYTE *work_ptr; 

ULONG return code ; 



/* Hook must return non-zero if command is supported. 

** This will be changed to zero if the command is unsupported. 



*/ 

return_code = ~0L; 

if (*msg == SGH_KEY) 

{ 

/* key hit -- could be any key (Shift, repeat, character, etc.) */ 

/* allow only upper case characters to be entered. 
** act only on modes that add or update characters in the buffer. 
*/ 

if ( (sgw->EditOp == EO_REPLACECHAR) || 
(sgw->EditOp == EO_INSERTCHAR) ) 

{ 

/* Code contains the ASCII representation of the character 
** entered, if it maps to a single byte. We could also look 
** into the work buffer to find the new character. 
** 

** sgw->Code == sgw->WorkBuf f er [sgw->Buf f erPos - 1] 
** 

** If the character is not a legal hex digit, don't use 

** the work buffer and beep the screen. 

*/ 

if ( ! IsHexDigit (sgw->Code) ) 

{ 

sgw->Actions |= SGA_BEEP; 

sgw->Actions &= ~SGA_USE; 

} 
else 

{ 

/* And make it upper-case, for nicety */ 

sgw->WorkBuf f er [sgw->Buf f erPos - 1] = ToUpper (sgw->Code) ; 
} 
} 
} 
else if (*msg == SGH_CLICK) 

{ 

/* mouse click 

** zero the digit clicked on 

*/ 

if (sgw->Buf f erPos < sgw->NumChars) 

{ 

work_ptr = sgw->WorkBuf f er + sgw->Buf f erPos ; 
*work_ptr = '0'; 
} 
} 
else 

{ 

/* UNKNOWN COMMAND 

** hook should return zero if the command is not supported. 

*/ 

return_code = ; 

} 

return (return_code) ; 
} 

/* 

** This is a function which converts register-parameter 

** hook calling convention into standard C conventions. 

** It only works with SAS C 5.0+ 

* * 

** Without the fancy asm stuff, you'd probably need to 



** write this in assembler. 

** You could conceivably declare all your C hook functions 
** this way, and eliminate the middleman (you'd initialize 
** the h_Entry field to your C function's address, and not 
** bother with the h_SubEntry field) . 
* * 

** This is nice and easy, though, and since we're using the 

** small data model, using a single interface routine like this 

** (which does the necessary saveds) , it might 

** actually turn out to be smaller to use a single entry point 

** like this rather than declaring each of many hooks saveds. 

*/ 

ULONG saveds asm hookEntry (register aO struct Hook *hookptr, 

register a2 void *object, 

register al void *message) 

{ 

return ( (*hookptr->h_SubEntry) (hookptr, object, message)); 

} 

/* 

** Initialize the hook to use the hookEntry () routine above. 

*/ 

void initHook (struct Hook *hook, ULONG (*ccode) ()) 

{ 

hook->h_Entry = hookEntry; 

hook->h_SubEntry = ccode; 

hook->h_Data =0; /* this program does not use this */ 

} 

/* 

** Process messages received by the sgg_Window. Quit when the close gadget 

** is selected. 

*/ 

VOID handleWindow (struct Vars *vars) 

{ 

struct IntuiMessage *msg; 

ULONG class; 

USHORT code; 

for (;;) 

{ 

Wait(lL << vars->sgg_Window->UserPort->mp_SigBit) ; 

while (msg = 

(struct IntuiMessage *) GetMsg (vars->sgg_Window->UserPort) ) 

{ 

/* Stash message contents and reply, important when message 

** triggers some lengthy processing 

*/ 

class = msg->Class; 

code = msg->Code; 

ReplyMsg ( (struct Message *)msg); 

switch (class) 

{ 

case IDCMP_GADGETUP : 

/* if a code is set in the hook after an SGH_KEY 

** command, where SGA_END is set on return from 

** the hook, the code will be returned in the Code 

** field of the IDCMP_GADGETUP message. 

*/ 

break; 



case IDCMP_CLOSEWINDOW: 
return; 
break; 



/* 

** isHexDigitO 
* * 

** Return TRUE if the character is a hex digit (0-9, A-F, a-f) 

*/ 

BOOL IsHexDigit (UBYTE test_char) 

{ 

test_char = ToUpper (test_char) ; 

if ( ( (test_char >= '0') && (test_char <= '9')) | 

( (test_char >= 'A') && (test_char <= 'F'))) 

return (TRUE) ; 
else 

return (FALSE) ; 
} 
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CUSTOM GADGETS 



Intuition also supports custom gadgets, where the application can supply to Intuition its own code to manage 
gadgets. This allows the creation of gadgets with behaviour quite different from standard boolean, 
proportional, or string gadgets. For example, it would be possible to create a dial gadget, where the user could 
rotate the knob of a gadget. The code for a custom gadget needs to respond to various commands and 
requests from Intuition, such as "is this pixel in your hit-area?", "please go active" and "please go inactive". 

Intuition has an object-oriented creation and delegation method called BOOPSI, that allows custom gadgets to 
be easily created, deleted, specialized from existing classes of custom gadget, and so on. See the Intuition 
chapter "BOOPSI" for details. 



Function Reference 



The following are brief descriptions of the Intuition functions that relate to the use of Intuition gadgets. See the 
Amiga ROM Kernel Reference Manual: Includes and Autodocs for details on each function call. 

Table 5-3: Functions for Intuition Gadgets 



Function 



Description 



AddGadget() 

AddGList() 

RemoveGadget() 

RemoveGList() 

RefreshGadgetsQ 
RefreshGListQ 



ModifyProp() 
NewModifyProp() 



Add a gadget to an open window or requester. 

Add some gadgets to an open window or requester. 
Remove a gadget from an open window or requester. 
Remove some gadgets from an open window or requester. 
Refresh all gadgets for the window or requester. 
Refresh some gadgets from the window or requester. 



Change the values of an open proportional gadget. 
Optimized version of ModifyPropQ. 



OnGadget() 
OffGadgetQ 



ActivateGadget() 
SetEditHook() 



Enable an open gadget. 
Disable an open gadget. 



Activate an open string gadget. 

Change the global edit hook for string gadgets. 
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Chapter 6 
INTUITION MENUS 



Menus are command and option lists associated wide an application window that the user can bring into view at any 
time. These lists provide the user with a simple way to access features of the application without having to remember 
or enter complex character-based command strings. 

The Intuition menu system handles all of the menu display without intervention from the application. The program 
simply submits an initialized list of data structures to Intuition and waits for menu events. 

This chapter shows how to set up menus that allow the user to choose from your programs commands and options. 



About Menus 



Intuition's menu system provides applications with a convenient way to group together and display the commands 
and options available Id the user. In most cases menus consist of a fixed list of text choices however this is not a 
requirement. Items in the menu list may be either graphic images or text, and the two types can be freely used 
together. The number of items in a menu can be changed if necessary. 

TYPES OF MENU CHOICES 

Menu choices represent either actions or attributes. Actions are analogous to verbs. An action is executed and then 
forgotten. Actions include such things as saving and printing files, calculating values and displaying information on the 
program. 

Attributes are analogous to adjectives. An attribute stays in effect until cancelled. Attributes include such things as 
pen type, color, draw mode and numeric format. 
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For instance, in a word processor, menus could be made to control the following types of features: 

File loading and saving (action). 

Editing functions (action). 

Formatting preferences (attributes). 

Printing functions (action). 

Current font and style (attributes). 

Menus can be set up such that some attribute items are mutually exclusive (selecting an attribute cancels the effects 
of one or more other attributes). For example, a drawing or graphics package may only allow one color to be active at 
a time-selecting a color cancels the previous active color. 

The program can also allow a number of attributes to be in effect at the same time. A common example of this 
appears in most word processing programs, where the text style may be bold, italic or underlined. Selecting bold does 
not rule out italic or underlined, in fact, all three may be active at the same time. 



THE MENU SYSTEM 

To activate the menu system, the user presses the menu button (the right mouse button). This displays the menu bar 
in the screen's title area. The menu bar displays a list of topics (called menus) that have menu items associated with 
them (see figure). The menu bar and menu items only remain visible/while the menu button is held down. 




Figure 6-1 : Screen with Menu Bar Displayed 
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When the mouse pointer is moved onto one of the menus in the menu bar, a list of menu items appears below the 
menu. The user can move the pointer within the list of menu items while holding down the menu button. A menu item 
will highlight when the pointer is over it and, if the item has a sub-item list, that list will be displayed. 

The specific menu that is displayed belongs to the active window. Changing the active window will change the menu 
bar and the choices available to the user. 

Unlike some other systems, the Amiga has no "standard menu" that appears in every menu bar. In fact, a window 
need not have any menus at all, thus holding down the mouse menu button does not guarantee the appearance of a 
menu bar. Although there is no "standard menu", Commodore does have a well-defined set of standards for menu 
design. These standards are covered in The Amiga User Interface Style Guide (also from Addison-Wesley). 

Selecting Menu Items 

To select a single menu item, the user releases the menu button when the pointer is over the desired item. Intuition 
can notify your program whenever the user makes a menu selection by sending an IDCMP message to your 
window's UserPort. Your application is then responsible for carrying out the action associated with the menu item 
selected. Action items lead to actions taken by the program while attribute items set values in the program for later 
reference. 



Menu selection is restricted to the most subordinate item. Top level menus are never selected. A menu item can be 
selected as long as it has no sub-items, and a sub-item may always be selected. (Of course, disabled menu items 
and sub-items cannot be selected.) Intuition menus allow the user to select multiple items by: 

Pressing and releasing the select button (left mouse button) without releasing the menu button. This selects 
the item and keeps the menus active so that other items may be selected. 



Holding down both mouse buttons and sliding the pointer over several items. This is called drag selecting. 
All items highlighted while dragging are selected. 

Drag selection, single selection with the select button and releasing the mouse button over an item can all be 
combined in a single operation. Any technique used to select a menu item is also available to select a menu sub-item. 

Menu Item Imagery 

Menu items can be graphic images or text. There is no conceptual difference between menus that display text and 
menus that display images, in fact, the two techniques may be used together. The examples in this chapter use text 
based menus to avoid the extra code required to define images. 

When the user positions the pointer over an item, We item can be highlighted through a variety of techniques. These 
techniques include a highlighted box the selected item, complementing the entire item and replacing the item with an 
alternate image or alternate text. 
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Attribute items can have an image rendered next to them, usually a checkmark, to indicate whether they are in effect 
or not. The checkmark is positioned to the left of the item. If the checkmark is present, the attribute is on. If not, the 
attribute is off. 

On the right side of menu items, command key alternatives may be displayed. Command key alternatives allow the 
user to make menu selections with the keyboard instead of the mouse. This is done by holding down the right Amiga 
key and then pressing the single character command key alternative listed next to the menu item. Command key 
alternatives appear as a reverse video, fancy "A", followed by the single character command key. 

Menu items or whole menus may be enabled or disabled. Disabling an item prevents the user from selecting it. 
Disabled items are ghosted (overwritten with a pattern of dots making the image less distinct) in order to distinguish 
them from enabled items. Menu help, a new feature of Release 2, allows the application to be notified when the user 
presses the help key at the same time the menu system is activated. This allows applications to provide a help 
feature for every item in its menus. Menu help may be requested on any level of a menu. 

MENU LIMITATIONS 

Menus are not layered so they lock the screen while they are displayed. While the screen is locked, it cannot render 
graphics into that screen-any rendering will be suspended until the menus are no longer displayed. 

Menus can only display a limited number of choices. Each window may have up to 31 menus, each menu may have 
up to 63 items, and each item may have up to 31 sub-items. 

Menus always appear at the top of the screen and cannot be repositioned or sized by the user. Moving the pointer to 
the menu bar may be inconvenient or time consuming for the user. (This is why it is generally a good idea to provide 
keyboard alternatives for menu items.) If some application has a function that the user will be performing repeatedly, 
it may be better to use a series of gadgets in the window (or a separate window) rather than a menu item. 

Alternatives to Menus 

You may want to use a requester or a window as an alternative to menus. A requester can function as a "super 
menu" using gadgets to provide the commands and options of a menu but with fewer restrictions on their placement, 
size and layout. See the chapter entitled "Intuition Requesters and Alerts," for more information. 

A window, also, could be substituted for a menu where an application has special requirements. Unlike menus, 
windows allow layered operations so that commands and options can be presented without forcing all other window 
output in the active screen to halt. 

Windows may be sized, positioned and depth arranged. This positioning flexibility allows the user to make other parts 
of the screen and other windows visible while they are entering data or selecting operations. The ability to access or 
view other data may be important in the user's choice of actions or attributes. See the "Intuition Windows" chapter for 



more details. 
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Setting Up Menus 



The application does not have to worry about handling the menu display. The menus are simply submitted to Intuition 
and the application waits for Intuition to send messages about the selection of menu items. These messages, along 
with the data in the menu structures, give the application all the information required for the processing of the user 
actions. 

Menus can be set up with the GadTools library on systems running Release 2 or a later version of the OS. Since 
GadTools makes menu set up easier and handles much of the detail work of menu processing (including adjusting to 
the current font selection), it should be used whenever possible. 

Under 1 .3 (V34) and older versions of the OS, GadTools is not available. To set up menus that work with these older 
systems, you use the Menu and Menultem structures. In general, for each menu in the menu bar, you declare one 
instance of the Menu structure. For each item or sub-item within a menu, you declare one instance of the Menultem 
structure. Text-based menus like the kind used in this chapter require an additional IntuiText structure for each 
menu, menu item and sub-item. All these structures are defined in <intuition/intuition.h>. 

The data structures used for menus are linked together to form a list known as a menu strip. For all the details of how 
the structures are linked and for listings of Menu and Menultem, see the "Menu Structures" section later in this 
chapter. 

SUBMITTING AND REMOVING MENU STRIPS 

Once the application has set up the proper menu structures, linked them into a list and attached the list to a window, 
the menu system completely handles the menu display. The menu strip is submitted to Intuition and attached to the 
window by calling the function SetMenuStrip(). 

BOOL SetMenuStrip ( struct Window *window, struct Menu Menu ); 

SetMenuStrip() always returns TRUE. This function can also be used to attach a single menu strip to multiple 
windows by calling SetMenuStrip() for each window (see below). 

Any menu strip attached to a window must be removed before the window is closed. To remove the menu strip, call 
ClearMenuStripO- 

void ClearMenuStrip ( struct Window Window ) ; 

The menu example below demonstrates how to use these functions with a simple menu strip. 

SIMPLE MENU EXAMPLE 

Menu concepts are explained in great detail later in this chapter; for now though it may be helpful to look at an 
example. Here is a very simple example of how to use the Intuition menu system. The example shows how to set up 
a menu strip consisting of a single menu with five menu items. The third menu item in the menu has two sub-items. 

The example works with all versions of the Amiga OS however it assumes that the Workbench screen is set up with 
the the Topaz 8 ROM font. If the font is different, the example will exit immediately since the layout of the menus 
depends on having a monospaced font with 8x8 pixel characters. 
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;/* simplemenu. c - Execute me to compile me with SAS C 5.10 

LC -bl -cfistq -v -y -J73 simplemenu. c 

Blink FROM LIB : c .o, simplemenu. o TO simplemenu LIBRARY LIB :LC . lib, LIB :Amiga . lib 



quit 

** simplemenu. c : how to use the menu system with a window under all OS versions. 

*/ 

#define INTUI_V3 6_NAMES_ONLY 

#include <exec/types . h> 
#include <exec/memory .h> 
#include <graphics/text . h> 
#include <intuition/intuition.h> 
#include <intuition/intuitionbase . h> 

#include <clib/exec_protos . h> 
#include <clib/graphics_protos . h> 
#include <clib/intuition_protos .h> 

#include <stdio.h> 
#include <string.h> 



#ifdef LATTICE 
int CXBRK(void) 
int chkabort (void) 
#endif 



return(O) ; } /* Disable Lattice CTRL/C handling */ 
return (0) ; } /* really */ 



/* These values are based on the ROM font Topaz 8 . Adjust these */ 
/* values to correctly handle the screen's current font. */ 
#define MENWIDTH (56+8) /* Longest menu item name * font width */ 

/* + 8 pixels for trim */ 

#define MENHEIGHT (10) /* Font height + 2 pixels */ 

struct Library *Gf xBase ; 
struct Library *IntuitionBase; 

/* To keep this example simple, we'll hard-code the font used for menu */ 
/* items. Algorithmic layout can be used to handle arbitrary fonts. */ 
/* Under Release 2, GadTools provides font-sensitive menu layout. */ 
/* Note that we still must handle fonts for the menu headers. */ 

struct TextAttr Topaz80 = 

{ 

"topaz. font", 8, 0, 



struct IntuiText menuIText [] 



o, 


1, 


JAM2, 


0, 


1, 


&Topaz8 0, 


o, 


1, 


JAM2, 


0, 


1, 


&Topaz8 0, 


o, 


1, 


JAM2, 


o, 


1, 


&Topaz8 0, 


o, 


1, 


JAM2, 


o, 


1, 


&Topaz8 0, 


o, 


1, 


JAM2, 


o, 


1, 


&Topaz8 0, 


o, 


1, 


JAM2, 


o, 


1, 


&Topaz8 0, 



"Open. . . ", NULL } , 
"Save", NULL }, 
"Print \273", NULL }, 
"Draft", NULL }, 
"NLQ", NULL }, 
"Quit", NULL } 



struct Menultem submenul [] 



{ /* Draft */ 

&submenul [1] , MENWIDTH-2, -2 , MENWIDTH, MENHEIGHT, 

ITEMTEXT | MENUTOGGLE | ITEMENABLED | HIGHCOMP, 

0, (APTR) &menuIText [3] , NULL, NULL, NULL, NULL 

}- 

{ /* NLQ */ 



NULL, MENWIDTH-2, MENHEIGHT-2, MENWIDTH, MENHEIGHT, 

ITEMTEXT | MENUTOGGLE | ITEMENABLED | HIGHCOMP, 
0, (APTR) kmenuIText [4] , NULL, NULL, NULL, NULL 
} 

}; 

struct Menultem menul [] = 

{ 

{ /* Open. . . */ 

imenul [1] , 0, 0, MENWIDTH, MENHEIGHT, 

ITEMTEXT | MENUTOGGLE | ITEMENABLED | HIGHCOMP, 
0, (APTR) kmenuIText [0] , NULL, NULL, NULL, NULL 

}. 

{ /* Save */ 

&menul[2], 0, MENHEIGHT , MENWIDTH, MENHEIGHT, 
ITEMTEXT | MENUTOGGLE | ITEMENABLED | HIGHCOMP, 
0, (APTR) &menuIText [1] , NULL, NULL, NULL, NULL 

}- 

{ /* Print */ 

&menul[3], 0, 2*MENHEIGHT , MENWIDTH, MENHEIGHT, 

ITEMTEXT | MENUTOGGLE | ITEMENABLED | HIGHCOMP, 

0, (APTR) kmenuIText [2] , NULL, NULL, &submenul [0] , NULL 

}- 

{ /* Quit */ 

NULL, 0, 3*MENHEIGHT , MENWIDTH, MENHEIGHT, 

ITEMTEXT | MENUTOGGLE | ITEMENABLED | HIGHCOMP, 

0, (APTR) &menuIText [5] , NULL, NULL, NULL, NULL 

}- 

}; 

/* We only use a single menu, but the code is generalizable to */ 
/* more than one menu. */ 

ttdefine NUM_MENUS 1 

STRPTR menutitle [NUM_MENUS] = { "Project" }; 

struct Menu menustrip [NUM_MENUS] = 

{ 

{ 

NULL, /* Next Menu */ 

0, 0, /* LeftEdge, TopEdge, */ 

0, MENHEIGHT, /* Width, Height, */ 

MENUENABLED, /* Flags */ 

NULL, /* Title */ 

&menul[0] /* First item */ 
} 

}; 

struct NewWindow mynewWindow = 

{ 

40,40, 300,100, 0,1, IDCMP_CLOSEWINDOW | IDCMP_MENUPICK, 
WFLG_DRAGBAR | WFLG_ACTI VATE | WFLG_CLOSEGADGET, NULL, NULL, 
"Menu Test Window", NULL, NULL, 0, 0, 0, 0, WBENCHSCREEN 

}; 

/* our function prototypes */ 

VOID handleWindow (struct Window *win, struct Menu *menuStrip) ; 

/* Main routine. */ 

/* */ 



VOID main(int argc, char **argv) 

{ 

struct Window *win=NULL; 

UWORD left, m; 

/* Open the Graphics Library */ 

GfxBase = OpenLibrary ( "graphics . library" , 33) ; 

if (GfxBase) 

{ 

/* Open the Intuition Library */ 

IntuitionBase = OpenLibrary ( "intuition. library" , 33); 

if (IntuitionBase) 

{ 

if ( win = OpenWindow (kmynewWindow) ) 

{ 

left = 2; 

for (m = 0; m < NUM_MENUS; m++) 

{ 

menustrip [m] .LeftEdge = left; 

menustrip [m] .MenuName = menutitle [m] ; 

menustrip [m] .Width = TextLength (&win->WScreen->RastPort , 

menutitle [m] , strlen (menutitle [m] ) ) + 8; 
left += menustrip [m] .Width; 

} 
if (SetMenuStrip (win, menustrip)) 

{ 

handleWindow (win, menustrip); 

ClearMenuStrip (win) ; 

} 
CloseWindow (win) ; 

} 
CloseLibrary (IntuitionBase) ; 

} 
CloseLibrary (GfxBase) ; 

} 



/* 

** Wait for the user to select the close gadget. 

*/ 

VOID handleWindow (struct Window *win, struct Menu *menuStrip) 

{ 

struct IntuiMessage *msg; 

SHORT done; 

ULONG class; 

UWORD menuNumber; 

UWORD menuNum; 

UWORD itemNum; 

UWORD SubNum; 

struct Menultem *item; 

done = FALSE; 

while (FALSE == done) 

{ 

/* we only have one signal bit, so we do not have to check which 

** bit broke the Wait() . 

*/ 

Wait(lL << win->UserPort->mp_SigBit) ; 

while ( (FALSE == done) && 



(msg = (struct IntuiMessage *) GetMsg (win->UserPort) ) ) 

{ 

class = msg->Class; 

if (class == IDCMP_MENUPICK) menuNumber = msg->Code; 

switch (class) 

{ 

case IDCMP_CLOSEWINDOW: 

done = TRUE; 

break; 
case IDCMP_MENUPICK; 

while ((menuNumber != MENUNULL) && (!done)) 

{ 

item = ItemAddress (menuStrip, menuNumber); 

/* process this item 

** if there were no sub-items attached to that item, 

** SubNumber will equal NO SUB . 

*/ 

menuNum = MENUNUM (menuNumber) ; 

itemNum = ITEMNUM (menuNumber) ; 

subNum = SUBNUM (menuNumber) ; 

/* Note that we are printing all values, even things 
** like NOMENU, NOITEM and NOSUB . An application should 
** check for these cases. 
*/ 

printf ("IDCMP_MENUPICK: menu %d, item %d, sub %d\n" , 
menuNum, itemNum, subNum) ; 

/* This one is the quit menu selection. . . 
** stop if we get it, and don't process any more. 
*/ 

if ( (menuNum == 0) && (itemNum == 4)) 
done = TRUE; 

menuNumber = item->NextSelect ; 

} 
break; 

} 
ReplyMsg ( (struct Message *)msg); 

} 
} 
} 

DISABLING MENU OPERATIONS 

If an application does not use menus at all, it may set the WFLG_RMBTRAP flag, which allows the program to trap 
right mouse button events for its own use. 

By setting the WFLG_RMBTRAP flag with the WA_Flags tag when the window is opened, the program indicates that 
it does not want any menu operations at all for the window. Whenever the user presses the right button while this 
window is active, the program will receive right button events as normal IDCMP_MOUSEBUTTONS events. 

CHANGING MENU STRIPS 

Direct changes to a menu strip attached to a window may be made only after the menu strip has been removed from 
the window. Use the ClearMenuStrip() function to remove the menu strip. It may be added back to the window after 
the changes are complete. 



Major changes include such things as adding or removing menus, items and sub-items; changing text or image data; 
and changing the placement of the data. These changes require the system to completely re-layout the menus. 

An additional function, ResetMenuStrip(), is available to let the application make small changes to the menus without 
the overhead of SetMenuStripQ. Only two things in the menu strip may be changed before a call to 
ResetMenuStrip(), they are: changing the CHECKED flag to turn checkmarks on or off, and changing the 
ITEMENABLED flag to enable/disable menus, items or sub-items. 

BOOL ResetMenuStript ( struct Window *window, struct Menu Araenu ) ; 

ResetMenuStrip() is called in place of SetMenuStripQ, and may only be called on menus that were previously 
initialized with a call to SetMenuStripQ. As with SetMenuStrip(), the menu strip must be removed from the window 
before calling ResetMenuStripQ. Note that the window used in the ResetMenuStripQ call does not have to be the 
same window to which the menu was previously attached. The window, however, must be on a screen of the same 
mode to prevent the need for recalculating the layout of the menu. 

If the application wishes to attach a different menu strip to a window that already has an existing menu strip, the 
application must call ClearMenuStrip() before calling SetMenuStrip() with the new menu strip. 

The flow of events for menu operations should be: 

1. OpenWindowTagList(). 

2. SetMenuStrip(). 

3. Zero or more iterations of ClearMenuStrip() and SetMenuStrip()/ResetMenuStrip(). 

4. ClearMenuStrip(). 

5. CloseWindow(). 
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SHARING MENU STRIPS 

A single menu strip may be attached to multiple windows in an application by calling SetMenuStripQ for each 
window. All of the windows must be on the same screen for this to work. Since menus are always associated with the 
active window on a given screen, and since only one window may be active on a screen at a time, only one window 
may display the shared menu strip at any given time. 

When multiple windows share a single menu strip, they will all "see" the same state of the menus, that is, changes 
made to the menu strip from one window will still exist when a new window is activated. If the application wishes to 
share menu strips but to have a different flag and enabled status for each window, the program may watch 
IDCMP_ACTIVEWINDOW for the windows and modify the menu strip to match the active window's requirements at 
that point. In addition, the application must also set IDCMP_MENUVERIFY to insure that the user can't access the 
menus of a newly activated window before the application can process the IDCMP_ACTIVEWINDOW message. 

ResetMenuStripQ may also be used to set the menus for the multiple windows as long as SetMenuStripQ is used 
first to attach the menu strip to any one window and no major changes are made to the menu strip before the calls to 
ResetMenuStripQ on subsequent windows. 

MENU SELECTION MESSAGES 

An input event is generated every time the user activates the menu system, either by pressing the mouse menu 
button or its keyboard equivalent (right Amiga Alt), or entering an appropriate command key sequence. The program 
receives a message of type IDCMP_MENUPICK detailing which menu items or sub-items were selected. Even if the 
user activates the menu system without selecting a menu item or sub item, an event is generated. 



Multi-Selection of Menu Items 

Each activation of the menu system generates only a single event. The user may select none, one or many items 
using any of the selection techniques described above; still, only one event is sent. 

The program finds out whether or not multiple items have been chosen by examining the field called NextSelect in 
the Menultem structure. The selected items are chained together through this field. This list is only valid until the user 
next activates the menu system, as the items are chained together through the actual Menultem structures used in 
the menu system. If the user reselects an item, the NextSelect field of that item will be overwritten. 

In processing the menu events, the application should first take the appropriate action for the item selected by the 
user, then check the NextSelect field. If the number there is equal to the constant MENUNULL, there is no next 
selection. However, if it is not equal to MENUNULL, the user has selected another option this one. The program 
should process the next item as well, by checking its NextSelect field, until it finds a NextSelect equal to NULL. 
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One following code fragment shows the correct way to process a menu event: 

struct IntuiMessage *msg; 
struct Menu *menuStrlp; 
UWORD menuNumber; 
struct Menultem *item; 

menuNumber = msg->Code; 

while (menuNumber != MENUNULL) 

{ 

item = ItemAddress (menuStrlp, menuNumber); 

/* process this item */ 

menuNumber = ltem->NextSelect ; 
} 

Intuition specifies which item or sub-item was selected in the IDCMP_MENUPICK event by using a shorthand code 
known as a menu number. Programs can locate the Menultem structure that corresponds to a given menu number 
by using the ltemAddress() function. This function translates a menu number into a pointer to the Menultem 
structure represented by the menu number. 

struct Menultem *ItemAddress ( struct Menu *menuStrlp, unsigned long menuNumber ); 

This allows the application to gain access to the Menultem structure and to correctly process multi-select events. 
Again, when the user performs multiple selection, the program will receive only one message of class 
IDCMP_MENUPICK. For the program to behave correctly, it must pay attention to the NextSelect field of the 
Menultem, which will lead to the other menu selections. 

There may be some cases in an application's logical flow where the selection of a menu item voids any further menu 
processing. For instance, after processing a "quit" menu selection, the application will, in general, ignore all further 
menu selections. 

MENU NUMBERS 

The menu numbers Intuition provides in the IDCMP_MENUPICK messages, describe the ordinal position of the menu 
in the linked list of menus, the ordinal position of the menu item beneath that menu, and (if applicable) the ordinal 
position of the sub-item beneath that menu item. Ordinal means the successive number of the linked items, in this 
case, starting from 0. 

To determine which menus and menu items (sub-items are special cases of menu items) were selected, use the 



following macros: 

Table 6-1 : Macros Used with Intuition Menus 



MENUNUM(num) Extracts the ordinal menu number from num. 

ITEMNUM(num) Extracts the ordinal item number from num. 

SUBNUM(num) Extracts the ordinal sub-item number from num. 



MENUNULL is the constant describing "no menu selection made." Likewise, NOMENU, NOITEM, and NOSUB 
describe the conditions "no menu chosen," "no item chosen" and "no sub-item chosen." 
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For example: 



if (menuNumber == MENUNULL) 

/* no menu selection was made */ 
else 

{ 

/* if there were no sub-items attached to that item, 
** SubNumber will equal NOSUB. 
*/ 

menuNum = MENUNUM (menuNumber) ; 
itemNum = ITEMNUM (menuNumber) ; 
subNum = SUBNUM (menuNumber) ; 
} 

The menu number received by the program is always set to either MENUNULL or a valid menu selection. If the menu 
number represents a valid selection, it will always have at least a menu number and a menu item number. Users can 
never select the menu text itself, but they always select at least an item within a menu. Therefore, the program 
always gets at least the menu selected and the menu item selected. If the menu item selected has a sub-item, a 
sub-item number will also be received. 

Just as it is not possible to select an entry in the menu bar, it is not possible to select a menu item that has attached 
sub-items. The user must select one of the options in the sub-item list before the program hears about the action as a 
valid menu selection. 

Help Is Available. The restrictions on what can be selected do not apply to 
IDCMP_MENUHELP messages. Using menu help, a user can select any component of a 
menu, including the menu header itself. 

How Menu Numbers Really Work 

The following is a description of how menu numbers really work. It should clarify why there are some restrictions on 
the number of menu components Intuition allows. Programs should not rely on the information given here to access 
menu number information directly though. Always use the Intuition menu macros to handle menu numbers. 

For convenience you should use the menus supplied. For example, to extract the item number from the menu 
number, call the macro ITEMNUM(menu_number); to construct a menu number, call the macro 
FULLMENUNUM(menu, item, sub). See the section at the end of this chapter for a more complete description of the 
menu number macros. 

Menu numbers are 16-bit numbers with 5 bits used for the menu number, 6 bits used for the menu item number, and 
5 bits used for the sub-item number. The three numbers only have meaning when used together to determine the 
position of the item or sub-item selected. 



bit 15 (MSB) 



bit (LSB) 



These bits are for 
the Sub-Items within 
the Menu item 


These bits are for 
the Menu Items 
within the Menu: 


These bits are for. 
the Menu number. 



The value all bits on means that no selection of this particular component was made. MENUNULL actually equals "no 
selection of any of the components was made" so MENUNULL always equals "all bits of all components on." 

For example, suppose that the program gets back the menu number (in hexadecimal) OxOCAO. In binary that equals: 
bit 15 (MSB) bit (LSB) 



bit 15 (MSB) 



bit (LSB) 




Sub-Item number = 1 



Menu Item number = 37 



Menu number = 



Again, the application should not examine these numbers directly. Use the macros described above to ensure proper 
menu handling. 

HELP KEY PROCESSING IN MENUS 

If the window is opened with the WA_MenuHelp tag, then user selection of the help key while menus are displayed 
will be detected. This tag is only available under V37 and later. 

When the user presses the Help key while using the menu system, the menu selection is terminated and an 
IDCMP_MENUHELP event is sent. The IDCMP_MENUHELP event is sent in place of the IDCMP_MENUPICK event, 
not in addition to it. IDCMP_MENUHELP never come as multi-select items, and the event terminates the menu 
processing session. 

The routine that handles the IDCMP_MENUHELP events must be very careful-it can receive menu information that 
is impossible under IDCMP_MENUPICK. IDCMP_MENUHELP events may be sent for any menu, item or sub-item in 
the menu strip, regardless of its state or position in the list. The program may receive events for items that are 
disabled or ghosted. IDCMP_MENUHELP events may send the menu header number alone, or the menu and item 
numbers, or all three components regardless of the items linked to the selected menu or item. This is done because it 
is reasonable for a user to request help in a disabled item or a menu header. If the user requests menu help on a 
disabled menu item or sub-item, try to explain to the user why that item is disabled and what steps are necessary to 
enable it. For instance, pressing help while a menu header is highlighted will trigger an IDCMP_MENUHELP event 
with a code that has a valid number for the menu, then NOITEM and NOSUB (IDCMP_MENUPICK would receive 
MENUNULL in this case.) 

The application should not take the action indicated by the IDCMP_MENUHELP event, it should provide the user with 
a description of the use or status of that menu. The application should never step through the NextSelect chain when 
it receives a IDCMP_MENUHELP event. 

MENU LAYOUT 



The Amiga allows great flexibility in the specification of fonts for the display. Default fonts are chosen by the user to 
suit their particular requirements and display resolution. The application should, where possible, use one of the 
preferred fonts. 

If the application did not open its own screen and completely specify the font for that screen, it must perform dynamic 
menu layout. This is because the Menu structure does not specify font. The menu header always uses the screen 
font and the program should update the size and position of these items at runtime to reflect the font. 
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The font for menu items may be specified in the Menultem structure, allowing the programmer to hard code values 
for the font, size and position of these items. This is not recommended. A specific font, while ideal on one system, 
may be less than ideal on another display type. Use the preferred font wherever possible. 

If the application does its own menu layout, it must use great care to handle the font in the menu strip and the font in 
each item or sub-item. The code should also keep items from running off the edges of the screen. 

See the description of ItemFill in the section "Menultem Structure" below for information on the positioning of 
multiple IntuiText or Image structures within the menu item. 

Applications should use the GadTools library menu layout routines whenever possible, rather than performing their 
own layout. See the chapter on the "GadTools Library" for more details. 

ABOUT MENU ITEM BOXES 

The item box is the rectangle containing the menu items or sub-items. 

The size and location of the item or sub-item boxes is not directly described by the application. Instead, the size is 
indirectly described by the placement of items and sub-items. When presented with a menu strip, Intuition first 
calculates the minimum size box required to hold the items. It then adjusts the box to ensure the menu display 
conforms to certain design philosophy constraints for items and sub-items. 



LMffll 



The lefl ecJge of the Menu E 
must be less than or equal to the 
left edge of the Menu Header 




The right edge of the Item Bo^ must be 
greater than or equal to the right edge 

Header. 



Figure 6-2: Example Item Box 
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The item box must start no further right than the leftmost position of the menu header's select box. It must end no 
further left than the rightmost position of the menu header's select box. The top edge of each item box must overlap 
the screen's title bar by one line. Each sub-item box must overlap its item's select box somewhere. 

Always Overlap. If your application is designed to work on systems prior to V37, do not leave 
space between sub-items in a sub-item list. This may cause flickering as the pointer moves off 
one item into the gap between the items. Even a single line between the items may cause 
flickering. This flickering is eliminated starting with V37. 




Figure 6-3: Example Subitem Box 
ATTRIBUTE ITEMS AND THE CHECKMARK 



Attribute items are items that have two states: selected and unselected. In the menu system, these items are often 
represented as items with checkmarks. If the checkmark is visible, then the item (or attribute) is selected. Otherwise, 
the attribute is not selected. 

Checkmarked items (attributes) may be toggle selected or mutually exclusive. Selecting a toggle selected item 
toggles its state-if it was selected, it will become unselected; and if it was unselected, it will become selected. 
Selecting a mutually exclusive item puts it in the selected state, while possibly clearing one or more other items, 
where it remains until it is cleared by the selection of some other item. 

A menu item is specified as a checkmark item by setting the CHECKIT flag in the Flags variable of the item's 
Menultem structure. 

The program can initialize the state of the checkmark (checked or not) by presetting the item's CHECKED flag. If this 
flag is set when the menu strip is submitted to Intuition, then the item is considered selected and the checkmark will 
he drawn. 

The program can use the default Intuition checkmark or provide a custom checkmark for the menus. To use a custom 
checkmark, the application must provide a pointer to the image with the WA_Checkmark tag when the window is 
opened. See the chapter "Intuition Windows" for details about supplying a custom checkmark. 
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The application must provide sufficient space at the left edge of the select box for the checkmark imagery. Constants 
are provided to standardize the space reserved in the menu for the checkmark. LOWCHECKWIDTH gives the 
amount of space required for checkmarks on low resolution screens and CHECKWIDTH gives space for all other 
screens. 

These constants specify the space required by the default checkmarks (with a bit of space for aesthetic purposes). If 
the image would normally be placed such that the LeftEdge of the image without the checkmark is 5, the image 
should start at 5 + CHECKWIDTH if CHECKIT is set. Also, the select box must be made CHECKWIDTH wider than it 
would be without the checkmark. It is generally accepted on the Amiga that only checkmarked items should be 
indented by the size of the checkmark, other items are left justified within their column. 



TOGGLE SELECTION 

Some of the checkmarked menu items may be of the toggle select type. Each time the user accesses such an item, it 
changes state, selected or unselected. To make an attribute item toggle select, set both the CHECKIT and the 
MENUTOGGLE flags for that menu item. Of course, the CHECKED flag may be preset to the desired initial state. 

MUTUAL EXCLUSION 

Mutual exclusion allows the selection of an item to cause other items to become unselected. 

For example, for a list of menu items describing the available sizes for a font, the selection of any size could unselect 
all other sizes. Use the MutualExclude variable in the Menultem structure to specify other menu items to be 
excluded when the user selects an item. Exclusion also depends upon the CHECKED and CHECKIT flags of the 
Menultem, as explained below. 

If CHECKED is not set, then this item is available to be selected. If the user selects this item, the CHECKED 
flag is set and the checkmark will be drawn to the left of the item. 

If the item selected has bits set in the MutualExclude field, the CHECKED flag is examined in the excluded 
items. If any item is currently CHECKED, its checkmark is erased, and its CHECKED flag is cleared. 

Mutual exclusion pertains only to items that have the CHECKIT flag set. Attempting to exclude items that do 
not have the CHECKIT flag set has no effect. 

Keep track of deselected items. It is up to the program to track internally which excluded 
items have been deselected. See the section "Enabling and Disabling Menus and Menu 
Items" below for more information. 

In the MutualExclude field, bit refers to the first item in the item list, bit 1 to the second, bit 2 to the third, and so on. 
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In the text style example described above, selecting plain excludes any other style. The MutualExclude fields of the 
four items would look like this: 



Plain 


OxFFFE 


Bold 


0x0001 


Italic 


0x0001 


Underline 


0x0001 



"Plain" is the first item on the list. It excludes all items except the first one. All of the other items exclude only the first 
item, so that bold, underlined text may be selected, while bold, plain text may not. 

MANAGING THE STATE OF CHECKMARKS 

To correctly handle checkmarked menu items, from time to time the application will need to read the CHECKED bit of 
its CHECKIT Menultems. It is not adequate to infer which items are checked by tracking what their state must have 
become. There are several reasons for this (although it's not important to understand the details; just the implication): 

Using multi-selection of menus, the user can toggle the state of a MENUTOGGLE item several times, yet the 
application will receive only a single IDCMP_MENUPICK event, and that item will only appear once one the 
NextSelect chain. 

When the user selects a mutually exclusive menu item, the IDCMP_MENUPICK event refers to that item, 
but Intuition doesn't notify your application of other items that may have been deselected through mutual 
exclusion. 

Prior to V36, unusually complex multi-selection operations could orphan menu selections. That is to say, 



some items that were selected may not even appear on the NextSelect chain. If such an item had 
checkmark, the state of that checkmark could nevertheless have changed. 

For complex multi-selection operations, the NextSelect chain will not be in select-order (a side-effect of the 
fact that the same Menultem cannot appear twice in the same NextSelect chain combined with the fix to the 
orphaning problems mentioned above). With certain mutual exclusion arrangements, it is impossible to 
predict the state of the checkmarks. 

If the user begins multi-selection in the menus and hits several checkmarked items, but then presses the 
help key, the application will receive an IDCMP_MENUHELP message. No IDCMP_MENUPICK message 
will have been sent. Thus, some checkmark changes could have gone unnoticed by the application. 

It is legal to examine the CHECKED state of a Menultem while that Menultem is still attached to a window. It is 
unnecessary to first call ClearMenuStrip(). 
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COMMAND KEY SEQUENCES 

A command key sequence is an event generated when the user holds down one of the Amiga keys (the ones with the 
fancy A) and presses one of the normal alphanumeric keys at the same time. There are two different command or 
Amiga keys, commonly known as the left Amiga key and the right Amiga key. 

Menu command key sequences are combinations of the right Amiga key with any alphanumeric character, and may 
be used by any program. These sequences must be accessed through the menu system. Command key sequences 
using the left Amiga key cannot be associated with menu items. 

Menu command key sequences, like the menus themselves, are only available for a window while that window is 
active. Each window may control these keys by setting keyboard shortcuts in the menu item structures which make 
up the window's menu strip. 

If the user presses a command key sequence that is associated with one of the menu items, Intuition will send the 
program an event that is identical to the event generated by selecting that menu item with the mouse. Many users 
would rather keep their hands on the keyboard than use the mouse to make a menu selection when accessing often 
repeated selections. Menu command key sequences allow the program to provide shortcuts to the user who prefers 
keyboard control. 

A command key sequence is associated with a menu item by setting the COMMSEQ flag in the Flags variable of the 
Menultem structure and by placing the ASCII character (upper or lower case) that is to be associated with the 
sequence into the Command variable of the Menultem structure. 

Command keys are not case sensitive and they do not repeat. Command keys are processed through the keymap so 
that they will continue to work even if the key value is remapped to another position. International key values are 
supported as long as they are accessible without using the Alt key (right Amiga-Alt maps to the right mouse button on 
the mouse). 




Figure 6 4: Menu Items with Command Key Short-cuts 

When items have alternate key sequences, the menu boxes show a special Amiga key glyph rendered roughly one 
character span plus a few pixels from the right edge of the menu select box. The command key used with the Amiga 
key is displayed immediately to the right of the Amiga key image, at the rightmost edge of the menu select box (see 
figure). 
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Space must be provided at the right edge of the select box for the Amiga key imagery and for the actual command 
character. Leave COMMWIDTH pixels on high resolution screens, and LOWCOMMWIDTH pixels on low resolution 
screens. The character's width may be calculated with the graphics library TextLength() call. In general, each column 
of items should leave enough room for the widest command character plus the width of the Amiga key imagery. 

ENABLING AND DISABLING MENUS AND MENU ITEMS 

Disabling menu items makes them unavailable for selection by the user. 

Disabled menus and menu items are displayed in a ghosted fashion; that is, their imagery is overlaid with a faint 
pattern of dots, making it less distinct. 

Enabling or disabling a menu or menu item is always a safe procedure, whether or not the user is currently using the 
menus. Of course, by the time you have disabled the item, the user may have already selected it. Thus, the program 
may receive a IDCMP_MENUPICK message for that item, even though it considers the item disabled. The program 
should be prepared to handle this case and ignore items that it knows are already disabled. This implies that the 
program must track internally which items are enabled and which are disabled. 

The OffMenu() and OnMenu() functions may be used to enable or disable items while a menu strip is attached to the 
window. 

void OffMenu ( struct Window *window, unsigned long menuNumber ) ; 
void OnMenu ( struct Window *wlndow, unsigned long menuNumber ) ; 



These routines check if the user is currently using the menus and whether the menus need to be redrawn to reflect 
the new states. If the menus are currently in use, these routines wait for the user to finish before proceeding. 



If the item component referenced by menuNumber equals NOITEM, the entire menu will be disabled or enabled. If 
the item component equates to an actual component number, then that item will be disabled or enabled. Use the 
macros defined below for the construction of menu numbers from their component parts. 

The program can enable or disable whole menus, just the menu items, or just single sub-items. 

To enable or disable a whole menu, set the item component of the menu number to NOITEM. This will 
enable or disable all items and any sub-items for that menu. 

To enable or disable a single item and all sub-items attached to that item, set the item component of the 
menu number to the item's ordinal number. If the item has a sub-item list, set the sub-item component of the 
menu number to NOSUB. If the item has no sub-item list, the sub-item component of the menu number is 
ignored. 

To enable or disable a single sub-item, set the item and sub-item components appropriately. 

It is also legal to remove the menu strip from each window that it is attached to (with ClearMenuStripO) change the 
ITEMENABLED or MENUENABLED flag of one or more Menu or Menultem structures and add the menu back using 
ResetMenuStrip() (in V36 or higher) or SetMenuStrip() (in any version of the OS). 
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INTERCEPTING NORMAL MENU OPERATIONS 

IDCMP_MENUVERIFY gives the program the opportunity to react before menu operations take place and optionally, 
to cancel menu operations. Menus may be completely disabled by removing the menu strip with a call to 
ClearMenuStrip(). 

A Warning on the MENUSTATE Flag 

The MENUSTATE flag is set by Intuition in Window.Flags when the menus of that window are in use. Beware: in 
typical event driven programming, such a state variable is not on the same timetable as the application's input 
message handling, and should not be used to draw profound conclusions in any program. Use 
IDCMP_MENUVERIFY to synchronize with the menu handling. 

Menu Verify 

Menu verify is one of the Intuition verification capabilities that allow an application to ensure that it is prepared for 
some action taken by Intuition before that action takes place. Through menu verify, Intuition allows all windows in a 
screen to verify that they are prepared for menu operations before the operations begin. In general, use menu verify if 
the program is doing something special to the display of a custom screen, and needs to be sure the operation has 
completed before menus are rendered. 

Any window can access the menu verify feature by setting the IDCMP_MENUVERIFY flag with the WAJDCMP tag 
when opening the window. When menus are activated in a screen which contains at least one window with 
IDCMP_MENUVERFIY set, menu operations will not proceed until all windows with the menu verify flag set reply to 
the notification or until the last message times out. The specific menu verify protocol is described below. 

In any case, it is vital that the application know when menu operations terminate, for only then does it have control of 
the screen again. For the active window, this is typically detected by watching for an IDCMP_MENUPICK message. If 
the program cancels the menu operations (MENUCANCEL), then it will instead receive an 
IDCMP_MOUSEBUTTONS message with code equal to MENUUP. Inactive windows will always receive 
IDCMP_MOUSEBUTTONS message with code equal to MENUUP. 

The active window is given special menu verify treatment. It receives the menu verify message before any other 
window and has the option of cancelling menu operations altogether. This could be used, for instance, to examine 
where the user has positioned the mouse when the right button was pressed. For example, the application may 
choose to allow normal menu operations to proceed only when the pointer is in the menu bar area. When the pointer 
is below the menu bar, then the application can choose to interpret the menu verify message as a right button event 



for some non-menu purpose. 

The program can tell if it is the active window for the verify event by examining the Code field of the 
IDCMP_MENUVERIFY message. If the Code field is equal to MENUWAITING, this window is not active and Intuition 
is simply waiting for verification that menu operations may continue. However, if the Code field is equal to 
MENUHOT, this window is active and it determines if menu operations should proceed. 

If it wishes menu operations to proceed, the active window should reply to the IDCMP_MENUVERIFY message 
without changing any values. To cancel the menu operation, change the code field of the message to MENUCANCEL 
boots replying m He message. 
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When the active window cancels the menu operation it will be sent an IDCMP_MOUSEBUTTONS message with 
code equal to MENUUP. In general, the window will not then receive an IDCMP_MENUPICK event as it cancelled the 
operation. However, the system should be prepared to handle an IDCMP_MENUPICK message with code equal to 
MENUNULL as one may be sent if the user releases the mouse button before the window replies to the message. 

The system takes no action on screen until the active window either replies to the menu verify event or the event 
times out. If the active window replies to the event in time and does not cancel the menu operation, Intuition will then 
move the screen title bar layer to the front, display the menu strip and notify all inactive menu verify windows of the 
operation. Layers will not be locked and the actual menus will not be swapped in until all these inactive windows reply 
to the message or time out. The inactive windows may not cancel the menu operation. 

If the user releases the menu button before the active window replies to the menu verify message, the menu 
operation will be cancelled and the active window will be sent an IDCMP_MOUSEBUTTONS message with code 
equal to MENUUP. When the active window finally replies to the message, it will receive an IDCMP_MENUPICK 
message with code equal to MENUNULL. 

If the event times out before the active window replies to the message, it will immediately be sent an 
IDCMP_MENUPICK message with code equal to MENUNULL. Then, when the user releases the menu button, the 
program will receive an IDCMP_MOUSEBUTTONS message with code equal to MENUUP. 

If an inactive window receives an IDCMP_MENUVERIFY message, it will always receive an 
IDCMP_MOUSEBUTTONS message with code equal to MENUUP when the menu operations are completed. 

About Double-Menu Requesters. The processing described above becomes more 
complicated when double-menu requester processing is introduced. If an application 
chooses to use a double-menu requester in a window with IDCMP_MENUVERIFY set, it 
should be aware that odd message combinations are possible. For instance, it is possible 
to receive only an I DCM P_M ENU VERI FY event with no following 
IDCMP_MOUSEBUTTONS event or IDCMP_MENUPICK event. Applications should 
avoid using double menu requesters if possible. 

Shortcuts and IDCMP_MENUVERIFY 

The idea behind IDCMP_MENUVERIFY is to synchronize the program with Intuition's menu handling sessions. The 
motive was to allow a program to arbitrate access to a custom screen's bitmap, so that Intuition would not render 
menus before the application was prepared for them. 

Some programs use IDCMP_MENUVERIFY to permit them to intercept the right mouse button for their own 
purposes. Other programs use it to delay menu operations while they recover from unusual events such as illegible 
colors of the screen or double buffering and related ViewPort operations. 

Menu shortcut keystrokes, for compatibility, also respect IDCMP_MENUVERIFY. They are always paired with an 
IDCMP_MENUPICK message so that the program knows the menu operation is over. This is true even if the menu 
event is cancelled. 
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IDCMP_MENUVERIFY and Deadlock 

The program may call ModifylDCMP() to turn IDCMP_MENUVERIFY and the other VERIFY IDCMP options off. It is 
important that this be done each and every time that the application is directly or indirectly waiting for Intuition, since 
Tuition may be waiting for the application, but not watching the window message port for IDCMP_MENUVERIFY 
events. The program cannot wait for a gadget or mouse event without checking also for any IDCMP_MENUVERIFY 
event messages that may require program response 

The most common problem area is System Requesters (AutoRequest( ) and EasyRequestQ). Before 
AutoRequestQ and EasyRequest() return control to the application, Intuition must be free to run and accept a 
response from the user. If the user presses the menu button, Intuition will wait for the program to reply to the 
IDCMP_MENUVERIFY event and a deadlock results. 

Therefore, it is extremely important to use ModifylDCMP() to turn off all verify messages before calling 
AutoRequestQ, EasyRequestQ or, directly or indirectly, AmigaDOS, since many error conditions in the DOS require 
user input in the form of an EasyRequestQ. Indirect DOS calls include OpenLibrary(), OpenDeviceQ, and 
OpenDiskFontQ. 

Beginning with V36, all windows that have the IDCMP_MENUVERIFY bit set must respond to Intuition within a set 
time period, or the menu operation will time out and the menu action will be cancelled. This prevents the deadlocks 
that were possible under previous versions of the operating system. 



Menu Data Structures 



The specifications for the menu structures are given below. Menus are the headers that show in the menu bar, and 
Menultems are the items and sub-items that can be chosen by the user. 

MENU STRUCTURE 

Here is the specification for a Menu structure: 

struct Menu 

{ 

struct Menu *NextMenu; 

WORD LeftEdge, TopEdge; 

WORD Width, Height; 

UWORD Flags; 

BYTE *MenuName ; 

struct Menultem Firstltem; 

WORD JazzX, JazzY, BeatX, BeatY; 
} 

The variables in the Menu structure have the following meanings: 

NextMenu 

This variable points to the next Menu header in the list. The last Menu in the list should have a NextMenu 
value of NULL 

LeftEdge, TopEdge, Width, Height 

These fields describe the select box of the header. Currently, any values supplied for TopEdge and Height 
are ignored by Intuition, which uses instead the screen's TopBorder for the TopEdge and the height of the 
screen's title bar for the Height. 
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LeftEdge is relative to the LeftEdge of the screen plus the screen's left border width, so if LeftEdge is 0, 
Intuition puts this header at the leftmost position. 



Flags 

The flag space is shared by the program and Intuition. The flags are: 

MENUENABLED 

This flag is for Intuition's use and indicates whether or not this Menu is currently enabled. Set this 
flag before submitting the menu strip to Intuition. If this flag is not set, the menu header and all 
menu items below it will be disabled, and the user will be able to view, but not select any of the 
items. After submitting the strip to Intuition, the disabled or enabled status may be changed by 
calling OnMenu() or OffMenuQ. 

MIDRAWN 

This flag indicates whether or not this menu's items are currently displayed to the user. 

MenuName 

This is a pointer to a NULL terminated character string that is printed on the screen's title bar starting at the 
LeftEdge of this menu's select box and at the TopEdge just below the screen title bar's top border. The text 
is rendered in the screen's font. 

Firstltem 

This points to the first Menultem structure in the linked list of this menu's items. 

JazzX, JazzY, BeatX, BeatY 

For internal use only. 

MENUITEM STRUCTURE 

The Menultem structure is used for both items and sub-items. There is no internal difference between items and 
sub-items, other than how they are linked into the menu strip. Items are linked directly to Menu structures through the 
Firstltem field, sub-items are linked to Menultem structures through the Subltem field. 

Here is the specification: 

struct Menultem 

{ 

struct Menultem *NextItem; 

WORD LeftEdge, TopEdge; 

WORD Width, Height; 

UWORD Flags; 

LONG MutualExclude; 

APTR ItemFill; 

APTR SelectFill; 

BYTE Command; 

struct Menultem *Subitem; 

UWORD NextSelect; 

}; 

The fields have the following meanings: 

Nextltem 

This field is a pointer to the next item in the list. The last item in the list should have a Nextltem value of 
NULL. 
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LeftEdge, TopEdge, Width, Height 

These fields describe the select box of the Menultem. The LeftEdge is relative to the LeftEdge of the 
Menu. The TopEdge is relative to the topmost position Intuition allows. TopEdge is based on the way the 
user has the system configured-which font, which resolution, and so on. Use for the topmost position. 



Flags 

The flag space is shared by the program and Intuition. See "Menultem Flags" below for a description of the 
flag bits. 

MutualExclude 

Use these bits to describe which of the other items, if any, are mutually excluded by this one. This long 
word refers to the items in the same menu as this one. A maximum of 32 items may be described by this 
variable, and they must be the first 32 items in the menu. This does not mean that there cannot be more 
than 32 items in any given menu, just that only the first 32 can be mutually excluded. 

ItemFIII 

This points to the data used in rendering this Menultem. It can point to either an instance of an IntuiText 
structure with text for this Menultem or an instance of an Image structure with image data. The program 
tells Intuition the type of data pointed to by this variable by setting or clearing the Menultem flag bit 
ITEMTEXT. (See "Menultem Flags" below for more details about ITEMTEXT. 

Note that the IntuiText or Image data need not be simple imagery, either of them may consist of multiple 
objects of the same type chained together as described in the chapter "Intuition Images, Line Drawing and 
Text". By chaining multiple IntuiText structures, the application may "fine tune" the positioning of text 
within each item. This is especially important for proportional fonts, where the width of the individual 
characters is not constant. This also allows items to have part of the text left justified and part right justified. 

SelectFill 

If HIGHIMAGE is set in the Flags variable as the Menultem highlighting mode, Intuition substitutes this 
alternate image or text for the original rendering described by ItemFill. The type of this structure must be 
the Same as ItemFill. SelectFill can point to either an Image or an IntuiText, where the type is determined 
by the setting of the ITEMTEXT flag. 

Command 

This variable is storage for a single alphanumeric character to be used as the command key substitute for 
this menu item. The command key sequence will be rendered in the menu display to the right of the item's 
select area, with a fancy, reverse-video A, followed by the command character. Case is ignored. 

If the flag COMMSEQ is set, the user can hold down the right Amiga key on the keyboard (to mimic using 
the right mouse menu button) and press the indicated key as a shortcut for using the mouse to select this 
item. 

Subltem 

If this item has a sub-item list, this variable should point to the Menultem structure describing the first 
sub-item in the list. 

There Is No Such Thing as a Sub-sub-item. A sub-item cannot have a sub-item attached to 
it. If this Menultem structure is not an item, this variable is ignored. 
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NextSelect 

This field is filled in by Intuition when this Menultem is selected by the user. After an item has been 
selected by the user, the program should process the request and then check the NextSelect field. If the 
NextSelect field is equal to MENUNULL, no other items were selected; otherwise, there is another item to 
process. See "Menu Numbers and Menu Selection Messages" above for more information about user 
selections 

MENUITEM FLAGS 

Here are the flags that can be set by the application in the Flags field of the Menultem structure: 

CHECKIT 

Set this flag to inform Intuition that this item is a checkmark item and should be preceded by a checkmark if 



the flag CHECKED is set. 

CHECKED 

For an item with the CHECKIT flag set, set this bit to specify that the checkmark is displayed. After the 
menu strip is submitted to Intuition, it will maintain the CHECKED bit based on effects from other items' 
mutual exclusions, or, for MENUTOGGLE items, from user accesses to this item. 

ITEMTEXT 

Set this flag if the representation of the item pointed to by the ItemFill field and, possibly, by SelectFill is 
text and points to an IntuiText structure. Clear this bit if the item is graphic and points to an Image 
structure. 

COMMSEQ 

If this flag is set, this item has an equivalent command key sequence set in the Command field of the 
Menultem structure. 

MENUTOGGLE 

This flag is used in conjunction with the CHECKIT flag. If MENUTOGGLE is set, a checkmark that is turned 
on may be turned off by selecting the item. This allows the user to toggle between the checked and 
non-checked states by repeatedly selecting the item. 

ITEMENABLED 

This flag describes whether or not this item is currently enabled. If an item is not enabled, its image will be 
ghosted and the user will not be able to select it. If this item has sub-items, all of the sub-items are disabled 
when the item is disabled. 

Set this flag before submitting the menu strip to Intuition. Once the menu strip has been submitted to 
Intuition, enable or disable items by calling OnMenu() or OffMenu(). 

HIGHFLAGS 

An item can be highlighted when the user positions the pointer over the item. These bits describe what type 
of highlighting will be used, if any. One of the following bits must be set, according to the type of 
highlighting desired: 

HIGHCOMP 

This complements all of the bits contained by this item's select box. 
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HIGHBOX 

This draws a box outside this item's select box. 

HIGHIMAGE 

This displays alternate imagery referenced in SelectFill. For alternate text, make sure that 
ITEMTEXT is set, and that the SelectFill field points to an IntuiText structure. For alternate image, 
ITEMTEXT must be cleared, and the SelectFill field must point to an Image structure. 

HIGHNONE 

This specifies no highlighting. 

The following two flags are used by Intuition: 

ISDRAWN 

Intuition sets this flag when this item's sub-items are currently displayed to the user and clears it when they 
are not. 

HIGHITEM 

Intuition sets this flag when this item is highlighted and clears it when the item is not highlighted. 



A Menu Example 



This example shows how to implement menus. The menu code is simply part of the processing for Intuition messages 
as shown in the 1DCMP example in the "Intuition Input and Output Methods" chapter. The example implements 
extended selection for menus, adaptation to fonts of different sizes, mutual exclusion and checkmarks. 

If possible, applications should use the menu layout routines available in the GadTools library, rather than doing the 
job themselves as this example does. See the "GadTools Library" chapter for more information. 

;/* menulayout.c - Execute me to compile me with SAS C 5.10 

LC -bl -cfistq -v -y -J73 menulayout.c 

Blink FROM LIB : c . o, menulayout . o TO menulayout LIBRARY LIB :LC . lib, LIB : Amiga . lib 

quit 

** menulayout.c - Example showing how to do menu layout in general. This example 

** also illustrates handling menu events, including IDCMP_MENUHELP events. 

* * 

** Note that handling arbitrary fonts is fairly complex. Applications that require 

V3 7 

** should use the simpler menu layout routines found in the GadTools library. 

*/ 

#define INTUI_V3 6_NAMES_ONLY 

#include <exec/types . h> 
#include <intuition/intuition.h> 
#include <intuition/intuitionbase . h> 
#include <graphics/gfxbase . h> 
#include <dos/dos.h> 
#include <clib/exec_protos . h> 
#include <clib/graphics_protos . h> 
#include <clib/intuition_protos .h> 
#include <stdlib.h> 
#include <stdio.h> 
#include <string.h> 



return(O) ; } /* Disable Lattice CTRL/C handling */ 
return (0) ; } /* really */ 



#ifdef LATTICE 

int CXBRK(void) 

int chkabort (void) 

#endif 

/* Our function prototypes */ 

BOOL processMenus (USHORT selection, BOOL done); 

BOOL handlelDCMP (struct Window *win) ; 

USHORT MaxLength (struct RastPort *textRPort, 

char_size) ; 

VOID setlTextAttr (struct IntuiText *f irst_IText , struct TextAttr *textAttr) ; 

VOID adjustltems ( struct RastPort *textRPort, struct Menultem *first_item, struct 

TextAttr *textAttr, 

USHORT char_size, USHORT height, USHORT level, USHORT left_edge) ; 
BOOL adjustMenus (struct Menu *first_menu, struct TextAttr *textAttr) ; 
LONG doWindow (void) ; 



struct Menultem *first item, USHORT 



/* Settings Item IntuiText */ 
struct IntuiText SettText [] = { 
{0,1, JAM2 , 2 , 1 , 

{0, 1, JAM2, CHECKWIDTH, 1, 
{0,1, JAM2 , CHECKWIDTH , 1 , 
{0,1, JAM2 , CHECKWIDTH , 1 , 

}; 



NULL, 


"Sound. . . ", 


NULL 


}. 


NULL, 


" Auto Save", 


NULL 


}. 


NULL, 


" Have Your Cake", 


NULL 


}. 


NULL, 


" Eat It Too", 


NULL 


} 



struct Menultem Settltem[] 



{ /* "Sound. . . " */ 

&SettItem[l] , 0, 0, 0, 0, ITEMTEXT I ITEMENABLED | HIGHCOMP, 0, 
(APTR) &SettText [0] , NULL, NULL, NULL, MENUNULL }, 
{ /* "Auto Save" (toggle-select, initially selected) */ 

&SettItem[2], 0, 0, 0, 0, 
ITEMTEXT | ITEMENABLED | HIGHCOMP | CHECKIT | MENUTOGGLE | CHECKED , , 
(APTR) &SettText [1] , NULL, NULL, NULL, MENUNULL }, 
{ /* "Have Your Cake" (initially selected, excludes "Eat It Too") */ 

&SettItem[3] , 0, 0, 0, 0, ITEMTEXT | ITEMENABLED | HIGHCOMP | CHECKIT | CHECKED, 8, 
(APTR) &SettText [2] , NULL, NULL, NULL, MENUNULL }, 
{ /* "Eat It Too" (excludes "Have Your Cake") */ 

NULL, 0, 0, 0, 0, ITEMTEXT | ITEMENABLED | HIGHCOMP | CHECKIT, 4, 
(APTR) &SettText [3] , NULL, NULL, NULL, MENUNULL } 

}; 



/* Edit Menu Item IntuiText */ 
struct IntuiText EditText [] = { 
{0,1, JAM2 ,2,1, NULL , 
{0,1, JAM2 ,2,1, NULL , 
{0,1, JAM2 ,2,1, NULL , 
{0,1, JAM2 ,2,1, NULL , 
{0,1, JAM2 ,2,1, NULL , 

}; 



"Cut", 


NULL } 


"Copy", 


NULL } 


"Paste" , 


NULL } 


"Erase" , 


NULL } 


"Undo" , 


NULL } 



/* Edit Menu Items */ 

struct Menultem Editltem[] = { 

{ /* "Cut" (key-equivalent: 
&EditItem[l] , 0, 0, 0, 0, 
(APTR) &EditText [0] , NULL, 

{ /* "Copy" (key-equivalent 
&EditItem[2] , 0, 0, 0, 0, 
(APTR) &EditText [1] , NULL, 

{ /* "Paste" (key-equivalent: 
&EditItem[3] , 0, 0, 0, 0, 
(APTR) &EditText [2] , NULL, 

{ /* "Erase" (disabled) */ 
&EditItem[4] , 0, 0, 0, 0, 
(APTR) &EditText [3] , NULL, 



X') */ 

ITEMTEXT | COMMSEQ | ITEMENABLED | HIGHCOMP, , 

' X ' , NULL , MENUNULL } , 

'O */ 

ITEMTEXT | COMMSEQ | ITEMENABLED | HIGHCOMP , , 
' C ' , NULL , MENUNULL } , 

V) */ 
ITEMTEXT | COMMSEQ | ITEMENABLED | HIGHCOMP , , 
'V, NULL, MENUNULL }, 



}; 



ITEMTEXT | HIGHCOMP, 0, 
NULL , NULL , MENUNULL } , 
{ /* "Undo" Menultem (key-equivalent: 'Z') */ 

NULL, 0, 0, 0, 0, ITEMTEXT | COMMSEQ | ITEMENABLED | HIGHCOMP, 0, 
(APTR) &EditText [4] , NULL, 'Z', NULL, MENUNULL } 



/* IntuiText for the Print Sub- Items */ 

struct IntuiText PrtText [] = { 

{0,1, JAM2,2,1, NULL, "NLQ" , NULL }, 
{0,1, JAM2,2,1, NULL, "Draft", NULL } 

}; 



/* Print Sub- Items */ 
struct Menultem Prtltem[] = 
{ /* "NLQ" */ 

&PrtItem[l] , 0, 0, 
(APTR) ScPrtText [0] , 
{ /* "Draft" */ 

NULL, 0, 0, 0, 0, ITEMTEXT | ITEMENABLED | HIGHCOMP, 0, 
(APTR) &PrtText [1] , NULL, NULL, NULL, MENUNULL } 



0, 0, ITEMTEXT | ITEMENABLED | HIGHCOMP, 0, 
NULL , NULL , NULL , MENUNULL } , 



/* Uses the >> character to indicate a sub-menu item. 

** This is \273 Octal, OxBB Hex or Alt-0 from the Keyboard. 



** NOTE that standard menus place this character at the right margin of the menu box. 
** This may be done by using a second IntuiText structure for the single character, 
** linking this IntuiText to the first one, and positioning the IntuiText so that the 
** character appears at the right margin. GadTools library will provide the correct 
behavior. 
*/ 



/* Project Menu Item IntuiText 
struct IntuiText ProjText [] = 
{0,1, JAM2 ,2,1, 
{0,1, JAM2 ,2,1, 
{0,1, JAM2 ,2,1, 
{0,1, JAM2 ,2,1, 
{0,1, JAM2 ,2,1, 
{0,1, JAM2 ,2,1, 
{0,1, JAM2 ,2,1, 

}; 



NULL, 


"New" , 


NULL } , 


NULL, 


"Open. . . " , 


NULL } , 


NULL, 


"Save", 


NULL } , 


NULL, 


"Save As. 


. . " , NULL } , 


NULL, 


"Print 


\273", NULL } 


NULL, 


"About 


' , NULL } , 


NULL, 


"Quit", 


NULL } 



/* Project Menu Items */ 
struct Menultem Projltemf] = { 

{ /* "New" (key-equivalent: 'N' */ 

&ProjItem[l] , 0, 0, 0, 0, ITEMTEXT | COMMSEQ | ITEMENABLED | HIGHCOMP, 0, 
(APTR) &ProjText [0] , NULL, 'N', NULL, MENUNULL }, 

{ /* "Open..." (key-equivalent: '0') */ 

&ProjItem[2] , 0, 0, 0, 0, ITEMTEXT | COMMSEQ | ITEMENABLED | HIGHCOMP, 0, 
(APTR) &Proj Text [1] , NULL, 'O', NULL, MENUNULL }, 

{ /* "Save" (key-equivalent: 'S') */ 

&ProjItem[3] , 0, 0, 0, 0, ITEMTEXT | COMMSEQ | ITEMENABLED | HIGHCOMP, 0, 
(APTR) &ProjText [2] , NULL, 'S', NULL, MENUNULL }, 

{ /* "Save As..." (key-equivalent: 'A') */ 

&ProjItem[4] , 0, 0, 0, 0, ITEMTEXT | COMMSEQ | ITEMENABLED | HIGHCOMP, 0, 
(APTR) &ProjText [3] , NULL, 'A', NULL, MENUNULL }, 



{ /* "Print" (has sub -menu) */ 
&ProjItem[5] , 0, 0, 0, 0, 
(APTR) &ProjText [4] , NULL, 

{ /* "About. . . " */ 

&ProjItem[6] , 0, 0, 0, 0, 
(APTR) &ProjText [5] , 



ITEMTEXT | ITEMENABLED | HIGHCOMP , , 
NULL, &PrtItem[0], MENUNULL }, 



}; 



ITEMTEXT | ITEMENABLED | HIGHCOMP , , 
NULL , NULL , NULL , MENUNULL } , 
{ /* "Quit" (key-equivalent: 'Q' */ 

NULL, 0, 0, 0, 0, ITEMTEXT | COMMSEQ | ITEMENABLED | HIGHCOMP, 0, 
(APTR) &ProjText [6] , NULL, 'Q', NULL, MENUNULL } 



/* Menu Titles */ 

struct Menu Menus [] = { 
{Menus [1] , 0, 
{Menus [2] , 70, 
{NULL, 12 0, 

}; 



0, 63, 0, MENUENABLED, "Project", 

0, 39, 0, MENUENABLED, "Edit", 

0, 88, 0, MENUENABLED, "Settings", 



&ProjItem[0] } , 
&EditItem[0] } , 
&SettItem[0] } , 



/* A pointer to the first menu for easy reference */ 
struct Menu *FirstMenu = Menus [0] ; 



/* Window Text for Explanation of Program */ 

struct IntuiText WinText [] = { 

{0, 0, JAM2, 0, 0, NULL, "How to do a Menu", NULL}, 
{0, 0, JAM2, 0, 0, NULL, "(with Style)", &WinText [0] } 

}; 



/* Globals */ 

struct Library *IntuitionBase = NULL; 

struct Library *Gf xBase = NULL; 

/* open all of the required libraries. Note that we require 

** Intuition V37, as the routine uses OpenWindowTags ( ) . 

*/ 

VOID main(int argc, char **argv) 

{ 

LONG returnValue; 

/* This gets set to RETURN_OK if everything goes well. */ 
returnValue = RETURN_FAIL; 

/* Open the Intuition Library */ 

IntuitionBase = OpenLibrary ( "intuition. library" , 37); 

if (IntuitionBase) 

{ 

/* Open the Graphics Library */ 

GfxBase = (struct GfxBase *) OpenLibrary ( "graphics . library" , 33); 

if (GfxBase) 

{ 

returnValue = doWindow () ; 

CloseLibrary (GfxBase) ; 

} 
CloseLibrary (IntuitionBase) ; 

} 
exit (returnValue) ; 

} 

/* Open a window with some properly positioned text. Layout and set 
** the menus, then process any events received. Cleanup when done. 
*/ 

LONG doWindow ( ) 

{ 

struct Window *window; 

struct Screen *screen; 

struct Drawlnfo *drawinfo; 

ULONG signalmask, signals; 

ULONG win_width, alt_width, win_height; 

LONG returnValue = RETURN_FAIL; 

BOOL done = FALSE; 

if (screen = LockPubScreen (NULL) ) 

{ 

if (drawinfo = GetScreenDrawInfo (screen) ) 

{ 

/* get the colors for the window text */ 

WinText [0] .FrontPen = WinText [1] . FrontPen = drawinfo- >dri_Pens [TEXTPEN] ; 

WinText [0] .BackPen = WinText [1] .BackPen = drawinfo- >dri_Pens [BACKGROUNDPEN] 

/* use the screen's font for the text */ 

WinText [0] . ITextFont = WinText [1] . ITextFont = screen- >Font ; 

/* calculate window size */ 

win_width = 100 + IntuiTextLength (& (WinText [0] )) ; 

alt_width = 100 + IntuiTextLength (& (WinText [1] )) ; 



if (win_width < alt_width) 

win_width = alt_width; 
win_height = 1 + screen- >WBorTop + screen- >WBorBottom + 
(screen->Font->ta_YSize * 5); 

/* calculate the correct positions for the text in the window */ 
WinText [0] .LeftEdge = (win_width - IntuiTextLength (& (WinText [0] ) ) ) >> 1 ; 
WinText [0] . TopEdge = 1 + screen- >WBorTop + (2 * screen->Font->ta_YSize) ; 
WinText [1] .LeftEdge = (win_width - IntuiTextLength (& (WinText [1] )) ) >> 1 ; 
WinText [1] .TopEdge = WinText [0] .TopEdge + screen- >Font->ta_YSize; 

/* Open the window */ 

window = OpenWindowTags (NULL, 
WA_PubScreen, screen, 

WA_IDCMP, IDCMP_MENUPICK | IDCMP_CLOSEWINDOW | IDCMP_MENUHELP, 
WA_Flags, WFLG_DRAGBAR | WFLG_DEPTHGADGET | WFLG_CLOSEGADGET | 

WFLG_ACTIVATE | WFLG_NOCAREREFRESH, 
WA_Left, 10, WA_Top, screen- >BarHeight + 1, 

WA_Width, win_width, WA_Height, win_height, 
WA_Title, "Menu Example", WA_MenuHelp, TRUE, 
TAG_END) ; 

if (window) 

{ 

returnValue = RETURN_OK; /* program initialized ok */ 

/* Give a brief explanation of the program */ 
PrintlText (window- >RPort, &WinText [1] ,0,0) ; 

/* Adjust the menu to conform to the font (TextAttr) */ 
adjustMenus (FirstMenu, window- >WScreen->Font) ; 

/* attach the menu to the window */ 
SetMenuStrip (window, FirstMenu) ; 

/* Set up the signals that you want to hear about ... */ 
signalmask = 1L << window- >UserPort->mp_SigBit; 

/* And wait to hear from your signals */ 
while ( Idone) 

{ 

signals = Wait (signalmask) ; 

if (signals & signalmask) done = handlelDCMP (window) ; 

} ; 

/* clean up everything used here */ 
ClearMenuStrip (window) ; 
CloseWindow (window) ; 

} 
FreeScreenDrawInfo (screen, drawinfo) ; 

} 
UnlockPubScreen (NULL, screen) ; 

} 
return (returnValue) ; 

} 

/* print out what menu was selected. Properly handle the IDCMP_MENUHELP 

** events. Set done to TRUE if quit is selected. 

*/ 

BOOL processMenus (USHORT selection, BOOL done) 



USHORT flags; 
USHORT menuNum, 



itemNum, subNum; 



menuNum = MENUNUM (selection) ; 
itemNum = ITEMNUM (selection) ; 
subNum = SUBNUM (selection) ; 

/* when processing IDCMP_MENUHELP, you are not guaranteed 

** to get a menu item. 

*/ 

if (itemNum != NOITEM) 

{ 

flags = ((struct Menultem *) ItemAddress (FirstMenu, (LONG) selection) ) ->Flags; 

if (flags & CHECKED) 

printf ( " (Checked) " ) ; 
} 



switch (menuNum) 

{ 

case 0: /* Project Menu */ 
switch (itemNum) 



ca 
ca 
ca 
ca 
ca 
ca 



NOITEM: printf (" Pro j ect Menu\n") 




1 
2 
3 
4 

switch 
{ 



printf ("New\n") ; 
printf ("Open\n") ; 
printf ( "Save\n" ) ; 
printf ("Save As\n") 
printf ("Print " ) ; 
(subNum) 



break 
break 
break 
break 
break 



ca 
ca 

} 
break; 



case 
case 

} 
break; 
se 5 : 
se 6 : 



case NOSUB: printf ( "ltem\n" ) ; break; 
0: printf ("NLQ\n") ; break; 
1: printf ( "Draft\n" ) ; break; 



printf ("About\n") 
printf ("Quit\n") ; 



done = TRUE ; 



break; 
break; 



case 1: /* Edit Menu 
switch (itemNum) { 
case NOITEM 
case 

1 



*/ 



case 
case 2 
case 3 
case 4 

} 
break; 
case 2 : 

switch (itemNum 
case NOITEM 
case 
case 1 
case 2 
case 3 



printf ("Edit Menu\n" 
printf ("Cut\n") ; 
printf ("Copy\n") ; 
printf ( " Paste\n" ) ; 
printf ( "Erase\n" ) ; 
printf ("Undo\n") ; 



/* Settings Menu */ 



break 
break 
break 
break 
break 
break 



printf ( "Settings Menu\n"); break; 
printf ( "Sound\n" ) ; break; 

printf ("Auto Save\n"); break; 
printf ("Have Your Cake\n"); break; 
printf ("Eat It Too\n"); break; 



} 

break; 



case NOMENU: /* No menu selected, can happen with IDCMP_MENUHELP */ 
printf("no menu\n"); 
break; 

} 
return (done) ; 

} 

/* Handle the IDCMP messages. Set done to TRUE if quit or closewindow is selected. */ 
BOOL handlelDCMP (struct Window *win) 

{ 

BOOL done; 

USHORT code, selection; 

struct IntuiMessage *message = NULL; 

ULONG class; 

done = FALSE; 

/* Examine pending messages */ 

while (message = (struct IntuiMessage *) GetMsg (win->UserPort) ) { 

class = message- >Class; 

code = message ->Code; 

/* When we're through with a message, reply */ 
ReplyMsg ( (struct Message *)message); 

/* See what events occurred */ 
switch (class) { 

case IDCMP_CLOSEWINDOW : 
done = TRUE; 
break; 
case IDCMP_MENUHELP : 

/* 

** The routine that handles the menus for IDCMP_MENUHELP must be very 
careful 

** it can receive menu information that is impossible under IDCMP_MENUPICK. 
** For instance, the code value on a IDCMP_MENUHELP may have a valid number 
** for the menu, then NOITEM and NOSUB . IDCMP_MENUPICK would get MENUNULL 
** in this case. IDCMP_MENUHELP never come as multi-select items, and the 
** event terminates the menu processing session. 

** Note that I do not keep the return value from the processMenus ( ) 
routine here- -the 

** application should not quit if the user selects "help" over the quit menu 
item. 

*/ 

printf ("IDCMP_MENUHELP: Help on "); 
processMenus (code, done) ; 
break; 
case IDCMP_MENUPICK; 

for ( selection = code; selection != MENUNULL; 

selection = (ItemAddress (FirstMenu, (LONG) selection) ) ->NextSelect) 

{ 

printf ("IDCMP_MENUPICK: Selected "); 
done = processMenus (selection, done) ; 

} 
break; 

} 
} 
return (done) ; 

} 



/* Steps thru each item to determine the maximum width of the strip */ 

USHORT MaxLength (struct RastPort *textRPort, struct Menultem *first_item, USHORT 

char_size) 

{ 

USHORT maxLength; 
USHORT total_textlen; 
struct Menultem *cur_item; 
struct IntuiText *itext; 
USHORT extra_width; 
USHORT maxCommCharWidth; 
USHORT commCharWidth; 

extra_width = char_size; /* used as padding for each item. */ 

/* Find the maximum length of a command character, if any. 

** If found, it will be added to the extra_width field. 

*/ 

maxCommCharWidth = ; 

for (cur_item = first_item; cur_item != NULL; cur_item = cur_item->NextItem) 

{ 

if (cur_item->Flags & COMMSEQ) 

{ 

commCharWidth = TextLength (textRPort ,& (cur_item->Command) , 1) ; 
if (commCharWidth > maxCommCharWidth) 
maxCommCharWidth = commCharWidth; 
} 
} 

/* if we found a command sequence, add it to the extra required space. Add 

** space for the Amiga key glyph plus space for the command character. Note 

** this only works for HIRES screens, for LORES, use LOWCOMMWIDTH . 

*/ 

if (maxCommCharWidth > 0) 

extra_width += maxCommCharWidth + COMMWIDTH; 

/* Find the maximum length of the menu items, given the extra width calculated above. 

*/ 

maxLength = ; 

for (cur_item = first_item; cur_item != NULL; cur_item = cur_item->NextItem) 

{ 

itext = (struct IntuiText *) cur_item->ItemFill ; 

total_textlen = extra_width + itext ->LeftEdge + 

TextLength (textRPort, itext->IText , strlen (itext->IText) ) ; 

/* returns the greater of the two */ 
if (total_textlen > maxLength) 
maxLength = total_textlen; 

} 
return (maxLength) ; 

} 

/* Set all IntuiText in a chain (they are linked through the NextText ** field) to the 

same font. */ 

VOID setlTextAttr (struct IntuiText *f irst_IText , struct TextAttr *textAttr) 

{ 

struct IntuiText *cur_IText; 

for (cur_IText = first_IText; cur_IText != NULL; cur_IText = cur_IText->NextText) 

cur_IText->ITextFont = textAttr; 
} 



/* Adjust the Menultems and Subltems */ 

VOID adjustltems (struct RastPort *textRPort, struct Menultem *first_item, 

struct TextAttr *textAttr, USHORT char_size, USHORT height, 

USHORT level, USHORT left_edge) 

{ 

register USHORT item_num; 
struct Menultem *cur_item; 
USHORT strip_width, subitem_edge; 

if (first_item == NULL) 
return; 

/* The width of this strip is the maximum length of its members. */ 
strip_width = MaxLength (textRPort , first_item, char_size) ; 

/* Position the items. */ 

for (cur_item = first_item, item_num = 0; cur_item != NULL; cur_item = 

cur_item->NextItem, item_num++) 

{ 

cur_item->TopEdge = (item_num * height) - level; 

cur_item->Lef tEdge = left_edge; 

cur_item->Width = strip_width; 

cur_item->Height = height; 

/* place the sub_item 3/4 of the way over on the item. */ 
subitem_edge = strip_width - (strip_width >> 2); 

setlTextAttr ( (struct IntuiText *) cur_item->ItemFill, textAttr); 

adjustltems (textRPort, cur_item->SubItem, textAttr, char_size, height, 1, subitem_edge) ; 
} 
} 

/* The following routines adjust an entire menu system to conform to the specified 

fonts' width and 

** height. Allows for Proportional Fonts. This is necessary for a clean look 

regardless of what the 

** users preference in Fonts may be. Using these routines, you don't need to specify 

TopEdge, 

** Lef tEdge, Width or Height in the Menultem structures. 

* * 

** NOTE that this routine does not work for menus with images, but assumes that all 

menu items are 

** rendered with IntuiText. 

* * 

** This set of routines does NOT check/correct if the menu runs off 

** the screen due to large fonts, too many items, lo-res screen. 

*/ 

BOOL adjustMenus (struct Menu *first_menu, struct TextAttr *textAttr) 

{ 

struct RastPort textrp = {o}; /* Temporary RastPort */ 

struct Menu *cur_menu; 

struct TextFont *font; /* Font to use */ 

USHORT start, char_size, height; 

BOOL returnValue = FALSE; 

/* open the font */ 

if (font = OpenFont (textAttr) ) 

{ 

SetFont (&textrp, font); /* Put font into temporary RastPort */ 



char_size = TextLength (&textrp, "n", 1); /* Get the Width of the Font */ 

/* To prevent crowding of the Amiga key when using COMMSEQ, don't allow the items to be less 
** than 8 pixels high. Also, add an extra pixel for inter-line spacing. 
*/ 
if (font->tf_YSize > 8) 

height = 1 + f ont->tf_YSize; 
else 

height =1+8; 

start =2; /* Set Starting Pixel */ 

/* Step thru the menu structure and adjust it */ 

for (cur_menu = first_menu; cur_menu != NULL; cur_menu = cur_menu->NextMenu) 

{ 

cur_menu->Lef tEdge = start; 

cur_menu->Width = char_size + 

TextLength (&textrp, cur_menu->MenuName, strlen (cur_menu->MenuName) ) ; 
adjustltems (&textrp, cur_menu->FirstItem, textAttr, char_size, height, 0, 0) ; 
start += cur_menu->Width + char_size + char_size; 

} 
CloseFont (font) ; /* Close the Font */ 

returnValue = TRUE; 

} 
return (returnValue) ; 

} 



Other Menu Macros 



The MENUNUMQ, ITEMNUM() and SUBNUMQ macros let an application break a menu number down into its 
component parts-the specific menu number, the item number and the sub-item number. (See the section on "Menu 
Numbers" earlier in this chapter for details.) Intuition also supplies macros that allow an application to construct a 
menu number given its components: 

SHIFTMENU(n) 

Create a properly masked and shifted specific menu number. 

SHIFTITEM(n) 

Create a properly masked and shifted item number. 

SHIFTSUB(n) 

Create a properly masked and shifted sub-item number. 

FULLMENUNUM( menu, item, sub ) 

Create a complete composite menu number from its components. 

Function Reference 

The following are brief descriptions of the Intuition functions that relate to the use of Intuition menus. See the Amiga 
ROM Kernel Reference Manual: Includes and Autodocs for details on each function call. 



Table 6-2: Functions for Intuition Menus. 



Function Description 

SetMenuStrip() Set a menu tor an open window. 

ClearMenuStrip() Clear the menu of an open window. 

ResetMenuStrip() Set a pre-calculated menu for an open window. 

itemAaaresso hino tne aadress ot a menu item rrom its position 



OffMenu() Disable a menu in a menu strip. 

OnMenu() Enable a menu in a menu strip. 



Chapter 7 

INTUITION REQUESTERS AND 
ALERTS 



This chapter explains how to create requesters, the information exchange boxes that both the system and 
applications can use for confirming actions, getting command options and similar operations. These boxes are called 
requesters because they generally request information from the user. 

Alerts provide a function similar to requesters but are reserved for emergency messages. Alerts are discussed later in 
this chapter. 

Types Of Requesters 

There are at least three kinds of display objects in Amiga terminology called requesters: true requesters, system 
requesters and ASL requesters. 

True requesters are general purpose display areas that can be thought of as temporary sub-windows. They display 
information to the user and allow the user to make a selection. True requesters always open within an existing 
window and are constrained to the boundaries of that window (often referred to as the parent window). If a requester 
extends beyond the edge of its parent window, either its position is adjusted or its graphics are clipped. True 
requesters always block input to their parent window as long as they are present. 

System requesters are typically used for warnings or to confirm an action the user has just initiated. System 
requesters differ from true requesters in that they cannot block input to the parent window. In fact, system requesters 
do not open in a parent window at all, but instead open their own separate window in the screen. Since these 
requesters are so different from true requesters, they will be discussed separately later in the chapter. See the 
sections on "Easy Requesters" and "System Requests" for more information. 

The third type of requester, the ASL requester, is a special purpose requester available only in Release 2 and later 
versions of the OS. ASL requesters provide an easy, standard way to get a filename from the user for load and save 
operations. They can also be used to get a font selection from the user. Since selecting a file or font name is one of 
the most common uses for a requester, it has been incorporated into Release 2 as a standard feature. For the details 
about ASL file and font requesters, see Chapter 1 6, "ASL Library". 
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True Requesters 

The primary function of a requester is to display information to the user from which the user is to make a selection. 
Conceptually, requesters are similar to menus since both menus and requesters offer options to the user. 
Requesters, however, go beyond menus because they can have customized imagery, can be placed anywhere in a 
window, can be activated by the application and may have any type of gadget attached. 

For instance, to select a color for a given operation using a menu could be awkward, especially in an application that 
supports a large number of colors. In that case a requester could be used instead (see figure). 
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Figure 7-1 : Requester Deluxe 

The ability of a true requester to block input to its parent window is important in understanding how requesters are 
used. When input is blocked by a true requester (also known as a modal requester), the user must take some action 
before the program will proceed further, such as making a selection, correcting an error condition, or acknowledging a 
warning. These are situations where a true (modal) requester is appropriate, however, keep in mind that your 
application should try to be as user-responsive as possible. Putting up a requester merely because you are in a 
phase of the program where it would be difficult to deal with user input is bad style. Modal requesters should be used 
only when the program requires user interaction before proceeding. 

True requesters can be created in a window in two different ways. 

An application can display a requester at any time by caning the Request() function. 

The application can declare a requester as the window's double menu requester, which the user can bring 
up with a double-click of the menu button (this method is rarely used). 
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CREATING APPLICATION REQUESTERS 

To create a requester, the application first allocates memory for or declares an instance of the Requester structure 
as defined in <intuition/intuition.h>. Once the Requester structure is set up, it is initialized with the lnitRequester() 
function. 

void InitRequester ( struct Requester 'requester) 

This function simply clears the Requester structure. The application should do further initialization depending on its 
needs. See the section on the "Requester Structure" below for an explanation of all the Requester fields and how to 
set them. 

A true (modal) requester is attached to its parent window and displayed with the Request() function. 

BOOL Request (struct Requester ^requester, struct Window *window) 

This function returns TRUE if the requester opens successfully or FALSE if the requester cannot be opened. If the 
requester opens successfully, menu and gadget input in the parent window is blocked as long as the requester is 



displayed. The application should process input events from the requester, which are sent to the parent window's 
Window.UserPort, until the requester is satisfied. 

To remove a requester from its parent window and update the display, use EndRequest(). 

void EndRequest( struct Requester "requester, struct Window *window ); 

This removes only the one requester specified. It is possible to set up a requester with a special gadget that, if 
selected, will automatically close the requester. In that case, EndRequestQ need not be called. If the program needs 
to cancel the request early, or cancel it only after some specific manipulation of the gadgets, EndRequestQ should 
be used. 

The application should always provide a safe way for the user to back out of a requester without taking any action 
that affects the user's work. Providing an escape hatch is important, for instance, a requester with the message 
"Overwrite File?" should allow the user to cancel the operation without losing the old data. 

REQUESTER I/O 

So long as a requester is active in a window, the only gadgets that can be used are those that are in the requester, 
plus all of the window's system gadgets except for the close gadget (i.e., the drag bar, size gadget, depth gadget, and 
zoom gadget). A requester also makes the menus of the parent window inaccessible. Additionally, mouse button and 
keyboard events will be blocked (unless the requester's NOISYREQ flag is set; see "Requester Structure" below). 
Mouse movement events, if enabled in the parent window (with WFLG_REPORTMOUSE) are not blocked. 

Requesters do not have their own IDCMP message ports. Instead, events for a requester are sent to the IDCMP port 
of the requester's parent window (Window.UserPort). Since the window's menus and application gadgets are 
inaccessible, no IDCMP events will be sent for them. 

Even though the window containing the requester is blocked for input, the user can work in another application or 
even in a different window of the same application without satisfying the requester. Only input to the parent window is 
blocked by a requester. 
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Output is not blocked by a requester so nothing prevents the application from writing to the window. Be aware, 
however, that the requester obscures part of the display and cannot be moved within the window so may limit the 
usefulness of any output you send to the parent window. There are several ways to monitor the comings and goings 
of requesters that anew the program to know if requesters are currently displayed in a given window. See "IDCMP 
Requester Features" below. 

The information displayed in a requester is placed in its own layer, so it does not overwrite the information in the 
window. Output to the window while the requester is displayed will not change the requester's display, it will go into 
the window's layer. The requester's layer is clipped to the window's boundaries, so the data in the requester is only 
visible if the window is large enough to allow for the complete display of that data. 

The requester will remain in the window and input will remain blocked until the user satisfies the request or the 
application removes the requester. Applications can set up some or all of the gadgets in the requester to 
automatically terminate the requester when the gadget is selected. This allows the requester to be removed from the 
window by user action. The application may also remove requesters from the window based on some event internal 
to the program. 

Multiple requesters may be nested in a single window. Such requesters must be satisfied in the reverses order in 
which they were posted; the last requester to be displayed must be satisfied first. Input will not be restored to a 
previous requester until all later requesters are satisfied.' 

Note that the application may not bring up a limitless number of requesters in a window. Each requester creates a 
new layer for rendering in its window and the system currently has a limit of ten layers per window. Normal windows 
use one layer for the window rendering, GimmeZeroZero windows use a second layer for the border rendering. This 
leaves a maximum of eight or nine simultaneous requesters open in a window at any given time. 



If the requester is being brought up only to display an error message, the application may want to use a less intrusive 
method of bringing the error to the user's attention than a requester. Requesters interrupt the flow of the user's work, 
and force them to respond before continuing. 

As an alternative to bringing up an error requester, the application could flash the screen instead with Intuition's 
DisplayBeep() function. This allows the application to notify the user of an error that is not serious enough to warrant 
a requester and to which the user does not really need to respond. For more information, see the description of 
DisplayBeep() in the "Intuition Screens" chapter. 

RENDERING REQUESTERS 

The application may choose to use Intuition's rendering facilities to display the requester, or it may define its own 
custom bitmap. The Requester structure is initialized differently according to the rendering method chosen. 

To use Intuition's rendering facilities, you supply a list of one or more display objects with the Requester structure 
and submit the Requester to Intuition, allowing it to draw the objects. These objects can include independent lists of 
Borders, IntuiText, Images and Gadgets. Note that the ability to provide a list of Image structures is new in V36, 
and the USEREQIMAGE flag must be set for them to be rendered. For more about Intuition rendering see the chapter 
on "Intuition Images, Line Drawing and Text". 
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The gadgets in a requester also have their own borders, images and text to add to the display imagery. Intuition will 
allocate the buffers, construct a bitmap that lasts for the duration of the display, and render the requester into the 
window. This rendering is all done over a solid color, filled background specified by the BackFill pen in the 
Requester structure. The backfill may be disabled by setting the NOREQBACKFILL flag (this also a new feature of 
V36). 

On the other hand, a custom requester may be designed with pre-defined, bitmap imagery for the entire object. The 
image bitmap is submitted to Intuition through the ImageBMap field of the Requester structure. The bitmap should 
be designed to reduce user confusion; gadgets should line up with their images, and the designer should attempt to 
use glyphs (symbols) familiar to the user. 

To provide imagery for the requester, applications should always try to use data structures attached to the Requester 
structure as described above. Although, rendering directly into the requester layer's RastPort is tolerated, it must be 
done with great care. 

First, a requester is allowed to have gadgets that automatically close the requester when they are selected 
(GACT_ENDGADGET). If such a gadget is selected, the requester, its layer, and its layer's RastPort will be deleted 
asynchronously to your application. If your application is trying to render directly into the requester at that time, the 
results are unpredictable. Therefore, do not put GACT_ENDGADGET gadgets into a requester if you plan on 
rendering directly into its RastPort. 

Second, recall that requesters are clipped to the inside of the window (not including the borders). If the window can 
be sized smaller such that the requester would be entirely clipped, the requester's layer may be deleted by Intuition. If 
your window's minimum size and the requester size and position are such that the requester can be completely 
clipped, then reading Requester.ReqLayer is unsafe without additional protection. It would be correct to 
LockLayerlnfoQ the screen's Layerjnfo, then check for the existence of the requester's ReqLayer, then render, 
then unlock. 

For reasons such as these, direct rendering is discouraged. 

REQUESTER REFRESH TYPE 

A requester appears in a Layer. By default, the requester layer is of type LAYERSMART, or, in window terminology, 
WFLG_SMART_REFRESH; so rendering is preserved in the requester when the window is moved or revealed. 

Requesters may also be simple refresh. This is the recommended type. If possible, make the requester a simple 



refresh layer requester by specifying the SIMPLEREQ flag. 

For all refresh types, Intuition will keep the gadget, border, image and bitmap imagery properly refreshed. 

REQUESTER DISPLAY POSITION 

The location of true requesters may be specified in one of three ways. The requester may either be a| constant 
location, which is an offset from the top left corner of the window; a location relative to the current location of the 
pointer; or a location relative to the center of the window. 

To display the requester as an offset from the upper left corner of the window, initialize the TopEdge and LeftEdge 
variables and clear the POINTREL flag. This will create a requester with a fixed position relative to the upper left 
corner for both normal requesters and double menu requesters. 
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Displaying the requester relative to the pointer can get the user's attention immediately and closely associates the 
requester with whatever the user was doing just before the requester was displayed in the window. However, only 
double menu requesters may be positioned relative to the pointer position. See below for more information on double 
menu requesters. 

Requesters that are not double menu requesters may be positioned relative to the center of the window on systems 
running Release 2 or a later version of the OS. This is done by setting the POINTREL flag and filling in the relative 
top and left of the gadget. Setting RelTop and RelLeft to zero will center the requester in the window. Positive values 
of RelTop and RelLeft will move the requester down and to the right, negative values will move it up and to the left. 

GADGETS IN REQUESTERS 

Each requester gadget must have the GTYP_REQGADGET flag set in the GadgetType field of its Gadget structure. 
This informs Intuition that this gadget is to be rendered in a requester rather than a window. 

Requesters can have gadgets in them that automatically satisfy the request and end the requester. When one of 
these gadgets is selected, Intuition will remove the requester from the window. This is equivalent to the application 
calling EndRequest(), and, if the request is terminated by selection of such a gadget, the application should not call 
EndRequestQ for that requester. 

Set the GACTENDGADGET flag in the Activation field of the Gadget structure to create a gadget that 
automatically terminates the requester. Every time one of the requester's gadgets is selected, Intuition examines the 
GACT_ENDGADGET flag. If GACT_ENDGADGET is set, the requester is removed from the display and unlinked 
from the window's active requester list. 

Requesters rendered via Intuition and those that use a custom bitmap differ in how their gadgets are |rendered. For 
requesters rendered via Intuition, the application supplies a regular gadget list just as it would for application gadgets 
in a window. 

In custom bitmap requesters, however, any gadget imagery is part of the bitmap supplied for the requester. Therefore 
the list of gadgets supplied for custom bitmap requesters should not provide gadget imagery but rather it should 
define only the select boxes, highlighting, and gadget types for the gadgets. 

The Gadget structures used with a custom bitmap requester should have their GadgetRender, SelectRender and 
GadgetText fields set to NULL as these will be ignored. Other gadget information-select box dimensions, 
highlighting, and gadget type-is still relevant. The select box information is especially important since the select box 
must have a well defined correspondence with the custom bitmap imagery supplied. The basic idea is to make sure 
that the user understands the requester imagery and gadgets. 

USING A REQUESTER TO BLOCK WINDOW INPUT 

There may be times when an application needs to block user input without a visible requester. In some cases, the 
application needs to be busy for a while. Other times, an application wants the blocking properties of a requester, but 



prefers to use a window instead of a true requester. In this case, the application can create a requester with no 
imagery, attaching it to the parent window to block input A new window may then be opened to act as the requester. 
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Some of the advantages of using a window as a requester instead of a real requester include: 

A window can be resized, and moves independently of the parent window. 

It is legal to render directly into a window. 

The window can have its own menus since only the parent window's menus are disabled (this is only 
occasionally useful). 

Certain code or a library you are using may not work in requesters (GadTools library is an example of this). 

Of course, using a true requester instead of a window has the advantage that the requester automatically moves and 
depth-arranges along with the parent window. 

A Requester Example 

To use a window as a requester, first bring up a zero-sized requester attached to the main window (this provides the 
blocking feature). Then, bring up your second window, or bring up a busy pointer. The following example illustrates 
bringing up a busy pointer. 

;/* blockinput.c - Execute me to compile me with SAS C 5.10 

LC -bl -cfistq -v -y -j73 blockinput.c 

Blink FROM LIB:c.o,blockinput . o TO blockinput LIBRARY LIB :LC . lib, LIB : Amiga . lib 

quit 

** To use a window as a requester, first bring up a zero-sized requester 
** attached to the main window (this provides the blocking feature) . 
** Then, bring up your second window, or bring up a busy pointer. The 
** following example illustrates bringing up a busy pointer. 

** blockinput.c -- program to demonstrate how to block the input from a 

** window using a minimal requester, and how to put up a busy pointer. 

*/ 

#define INTUI_V3 6_NAMES_ONLY 

#include <exec/types . h> 
#include <intuition/intuition.h> 

#include <clib/exec_protos . h> 
#include <clib/intuition_protos .h> 

#include <stdio.h> 

#ifdef LATTICE 

int CXBRK(void) { return(O); } /* Disable Lattice CTRL/C handling */ 

int chkabort (void) { return(O); } /* really */ 

#endif 

/* our function prototypes */ 

BOOL beginWait (struct Window *win, struct Requester *waitRequest) ; 
VOID endWait (struct Window *win, struct Requester *waitRequest) ; 
VOID processIDCMP (struct Window *win) ; 

struct Library *IntuitionBase; 



/* data for a busy pointer. 

** this data must be in chip memory! 

*/ 



UWORD 



chip waitPointer [] 



{ 

0x0000, 0x0000, 



/* reserved, must be NULL */ 



0x0400, 
0x0000, 
0x0100, 
0x0000, 
0x07C0, 
OxlFFO, 
0x3FF8, 
0x3FF8, 
0X7FFC, 
0X7EFC, 
0X7FFC, 
0x3FF8, 
0x3FF8, 
OxlFFO, 
0x07C0, 
0x0000, 



0x07C0, 
0x07C0, 
0x0380, 
0x07E0, 
0xlFF8, 
0x3FEC, 
0x7FDE, 
0x7FBE, 
0xFF7F, 
OxFFFF, 
OxFFFF, 
0X7FFE, 
0X7FFE, 
0X3FFC, 
0xlFF8, 
0x07E0, 



0x0000, 0x0000, 



}; 



/* reserved, must be NULL */ 



** main ( ) 

** Open a window and display a busy-pointer for a short time then wait for 

** the user to hit the close gadget (in processIDCMP ( ) ) . Normally, the 

** application would bracket sections of code where it wishes to block window 

** input with the beginWait ( ) and endWait ( ) functions. 

*/ 

VOID main (int argc, char **argv) 

{ 

struct Window *win; 

if (IntuitionBase = OpenLibrary ( "intuition. library" , 37) ) 



if (win = OpenWindowTags (NULL, 

WA_IDCMP , IDCMP_CLOSEWINDOW | IDCMP_INTUITICKS , 

WA_Activate, TRUE, 

WA_Width, 32 0, 

WA_Height, 10 0, 

WA_CloseGadget, TRUE, 

WA_DragBar , TRUE , 

WA_DepthGadget , TRUE, 

WA_SizeGadget, TRUE, 

WA_MaxWidth, ~0, 

WA_MaxHe ight , ~ , 

TAG_END) ) 

{ 

processIDCMP (win) ; 
CloseWindow (win) ; 

} 
CloseLibrary (IntuitionBase) ; 

} 



/* 

** beginWait ( ) 

** Clear the requester with InitRequester . This makes a requester of 
** width = 0, height = 0, left = 0, top = 0; in fact, everything is zero. 
** This requester will simply block input to the window until 
** EndRequest is called. 

* * 

** The pointer is set to a reasonable 4-color busy pointer, with proper offsets. 

*/ 

BOOL beginWait (struct Window *win, struct Requester *waitRequest) 

{ 

extern UWORD chip waitPointer [] ; 

InitRequester (waitRequest) ; 
if (Request (waitRequest , win)) 

{ 

SetPointer (win, waitPointer, 16, 16, -6, 0); 
SetWindowTitles (win, "Busy - Input Blocked" , (UBYTE *)~0); 
return (TRUE) ; 

} 
else 

return (FALSE) ; 
} 

/* 

** endWaitO 

* * 

** Routine to reset the pointer to the system default, and remove the 

** requester installed with beginWait ( ) . 

*/ 

VOID endWait (struct Window *win, struct Requester *waitRequest) 

{ 

ClearPointer (win) ; 
EndRequest (waitRequest , win); 
SetWindowTitles (win, "Not Busy" , (UBYTE *)~0); 
} 

/* 

** processIDCMP ( ) 

** Wait for the user to close the window. 

*/ 

VOID processIDCMP (struct Window *win) 

{ 

WORD done; 

struct IntuiMessage *msg; 

ULONG class; 

struct Requester myreq; 

UWORD tick_count; 

done = FALSE; 

/* Put up a requester with no imagery (size zero) . */ 
if (beginWait (win, kmyreq) ) 

{ 
/* 

** Insert code here for a window to act as the requester. 

*/ 



/* We'll count down INTUITICKS, which come about ten times 

** a second. We'll keep the busy state for about three seconds. 

*/ 

tick_count = 3 0; 

} 

while ( Idone) 

{ 

Wait(lL << win->UserPort->mp_SigBit) ; 

while (NULL != (msg = (struct IntuiMessage *) GetMsg (win->UserPort) ) ) 

{ 

class = msg->Class; 

ReplyMsg ( (struct Message *)msg); 

switch (class) 

{ 

case IDCMP_CLOSEWINDOW: 

done = TRUE; 

break; 

case IDCMP_INTUITICKS: 

if (tick_count > 0) 

{ 

if ( - -tick_count == 0) endWait (win, kmyreq) ; 

} 
break; 

} 
} 
} 
} 

DOUBLE MENU REQUESTERS 

A double menu requester is exactly like other requesters with one exception: it is displayed only when the user double 
clicks the mouse menu button. Double menu requesters block input in exactly the same manner as other true 
requesters. A double menu requester is attached to a window by calling SetDMRequest(). 

BOOL SetDMRequest ( struct Window *window, struct Requester 'requester ) ; 

This call does not display the requester, it simply prepares it for display. The requester will be brought up when the 
user double clicks the mouse menu button. The parent window will receive IDCMP_REQSET and 
IDCMP_REQCLEAR messages when the requester is added and removed. 

To prevent the user from bringing up a double menu requester, unlink it from the window by calling 
ClearDMRequest(). If a double menu request is set for a window, ClearDMRequest() should be called to remove the 
requester before that window is closed. 

BOOL ClearDMRequest ( struct Window *window ) ; 

This function unlinks the requester from the window and disables the ability of the user to bring it up. 
ClearDMRequest() will fail if the double menu request is currently being displayed. 

Double menu requesters can be positioned relative to the current mouse pointer position. For a mouse relative 
requester, specify POINTREL in the Flags field and initialize the RelLeft and RelTop variables. RelLeft and RelTop 
describe the offset of the upper, left corner of the requester from the pointer position at the time the requester is 
displayed. These values can be either negative or positive. 



The values of RelLeft and RelTop are only advisory; the actual position will be restricted such that the requester is 
entirely contained within the borders of its parent window, if possible. The actual top and left positions are stored in 
the TopEdge and LeftEdge variables. 

Positioning relative to the mouse pointer is possible only with double menu requesters. Setting POINTREL in a 
requester which is not a double menu requester will position the requester relative to the center of the window. 

IDCMP REQUESTER FEATURES 

Intuition can notify your application about user activity in the requester by sending a message to the parent window's 
IDCMP port (Window.UserPort). When using the IDCMP for input, the following IDCMP flags control how requester 
input events will be handled. 

IDCMP_REQSET 

With this flag set, the program will receive a message whenever a requester opens in its window. The 
application will receive one IDCMP_REQSET event for each requester opened in the window. 

IDCMP_REQCLEAR 

With this flag set, the program will receive a message whenever a requester is cleared from its window. 
The application will receive one IDCMP_REQCLEAR event for each requester closed in the window. By 
counting the number of IDCMP_REQSET and IDCMP_REQCLEAR events, the application may determine 
how many requesters are currently open in a window. 
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IDCMP_REQVERIFY 

With this flag set, the application can ensure that it is ready to allow a requester to appear in the window 
before the requester is displayed. 

When the program receives an IDCMP_REQVERIFY message, it must reply to that message before the 
requester is added to the window. If multiple requesters are opened in the window at the same time, only 
the first one will cause an IDCMP_REQVERIFY event. It is assumed that once a requester is in a window 
others may be added without the program's consent. After the requester count drops to zero and there are 
no open requesters in the window, the next requester to open will cause another IDCMP_REQVERIFY 
event. 

IDCMPREQVERIFY is ignored by the Request() function. Since RequestQ is controlled by the 
application, it is assumed that the program is prepared to handle the request when calling this function. 
Since the system does not render true requesters into an application's window (EasyRequestQ and 
AutoRequest() come up in their own window, not in the application's window), IDCMP_REQVERIFY will 
only control the timing of double menu requesters. 

These flags are set when the parent window is first opened by using either the WA_IDCMP tag or 
NewWindow.lDCMPFIags. They can also be set after the parent window is open by using the ModifylDCMP() call. 
See the chapter entitled "Intuition Input and Output Methods," for further information about these IDCMP flags. See 
the "Intuition Windows" chapter for details on setting IDCMP flags when a window is opened. 



Requester Structure 



Unused fields in the Requester structure should be initialized to NULL or zero before using the structure. For global 
data that is pre-initialized, be sure to set all unused fields to zero. For dynamically allocated structures, allocate the 
storage with the MEMF_CLEAR flag, or call the lnitRequester() function to clear the structure. 

Requesters are Initialized According to Their Type. See "Rendering Requesters" and 
"Gadgets in Requesters" above for information about how the initialization of the 
structure differs according to how the requester is rendered. 



The specification for a Requester structure, defined in <intuition/intuition.h>, is as follows. 

struct Requester 

{ 

struct Requester *01derRequest ; 

WORD LeftEdge, TopEdge; 

WORD Width, Height; 

WORD RelLeft, RelTop; 

struct Gadget * ReqGadget; 

struct Border *ReqBorder; 

struct IntuiText *ReqText; 

UWORD Flags; 

UBYTE Backfill; 

struct Layer *ReqLayer; 

UBYTE ReqPadl[32]; 

struct BitMap *ImageBMap; 

struct Window *RWindow; 

struct Image *ReqImage; 

UBYTE ReqPad2 [32] ; 

}; 
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Here are the meanings of the fields in the Requester structure 

OlderRequest 

For system use, initialize to NULL. 

LeftEdge, TopEdge 

The location of the requester relative to the upper left corner of the window. These values must be set if the 
POINTREL flag is not set. Use RelLeft and RelTop for POINTREL requesters. 

Width, Height 

These fields describe the size of the entire requester rectangle, containing all the text and gadgets. 

RelLeft, RelTop 

These values are only used if the POINTREL flag in the requester's Flags field is set. 

If the requester is a double menu requester and POINTREL is set then these values contain the relative 
offset of the requester's upper left corner from the current pointer position. 

If the requester is not a double menu requester and POINTREL is set, then these values contain the 
relative offset of the requester's center from the center of the window that the requester is to be displayed 
in. For example, using POINTREL with a requester which is not a double menu requester with RelLeft and 
RelTop of zero will center the requester in the window. The requester is centered within the inner part of 
the window, that is, within the inside edge of the window's borders. 

If the requester is POINTREL and part of the containing box will appear out of the window, Intuition will 
adjust the requester so that the upper left corner is visible and as much of the remaining box as possible is 
visible. The adjustment attempts to maintain the requester within the window's borders, not within the 
window's bounding box. 

ReqGadget 

This field is a pointer to the first in a linked list of Gadget structures. GTYPREQGADGET must be 
specified in the GadgetTypes field of all Gadget structures that are used in a requester. Take care not to 
specify gadgets that extend beyond the Requester rectangle specified by the Width and Height fields, as 
Intuition does no boundary checking. 

For requesters with custom imagery, where PREDRAWN is set, ReqGadget points to a valid list of 
gadgets, which are real gadgets in every way except that the gadget text and imagery information are 



ignored (and can be NULL). The select box, highlighting, and gadget type data are still used. Try to 
maintain a close correspondence between the gadgets' select boxes and the supplied imagery. 

String Gadgets and Pre-drawn Requesters. Intuition will not render string gadget text in a 
predrawn requester. The application must use other rendering means than the predrawn 
bitmap if it wishes to use string gadgets with a requester. 

Req Border 

This field is a pointer to an optional linked list of Border structures for drawing lines around and within the 
requester. The lines specified in the border may go anywhere in the requester; they are not confined to the 
perimeter of the requester. 

For requesters with custom imagery, where PREDRAWN is set, this variable is ignored and may be set to 
NULL. 



ReqText 



Flags 
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This field is a pointer to an optional linked list of IntuiText structures containing text for the requester. This 
is for general text in the requester. 

For requesters with custom imagery, where PREDRAWN is set, this variable is ignored and can be set to 
NULL. 

The following flags may be specified for the Requester: 

POINTREL 

Specify POINTREL to indicate that the requester is about to appear in a relative rather than a fixed 
position. 

For double menu requesters, the position is relative to the pointer. Otherwise, the position of 
POINTREL requesters is relative to the center of the window. 

See the discussion of RelLeft and RelTop, above. 

PREDRAWN 

Specify PREDRAWN if a custom BitMap structure is supplied for the requester and ImageBMap 
points to the structure. 

NOISYREQ 

Normally, when a requester is active, any gadget, menu, mouse and keyboard events within the 
parent window are blocked. Specify the NOISYREQ requester flag to allow keyboard and mouse 
button IDCMP events to be posted, even though the requester is active in the parent window. 

If the NOISYREQ requester flag is set, the application will receive IDCMP_RAWKEY, 
IDCMP_VANILLAKEY and IDCMP_MOUSEBUTTONS events. Note that with NOISYREQ set, 
IDCMP_MOUSEBUTTON events will also be sent when the user clicks on any of the blocked 
gadgets in the parent window. 

Although the reporting of mouse button events depends on NOISYREQ, mouse movement events 
do not. IDCMP_MOUSEMOVE events are reported if the window flag WFLG_REPORTMOUSE is 
set in the parent window, or if one of the requester gadgets is down and has the 
GACT_FOLLOWMOUSE flag set. This is true even if the requester is a double menu requester. 

USEREQIMAGE 

Render the linked list of images pointed to by Reqlmage after rendering the BackFill color but 
before gadgets and text. 

NOREQBACKFILL 



Do not backfill the requester with the BackFill pen. 
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In addition, Intuition uses these flags in the Requester: 

REQOFFWINDOW 

Set by Intuition if the requester is currently active but is positioned off window. 

REQACTIVE 

This flag is set or cleared by Intuition as the requester is posted and removed. The active requester 
is indicated by the value of Window.FirstRequest. 

SYSREQUEST 

This flag is set by Intuition if this is a system generated requester. Since the system will never 
create a true requester in an application window, the application should not be concerned with this 
flag. 

BackFill 

BackFill is the pen number to be used to fill the rectangle of the requester before any drawing takes place. 
For requesters with custom imagery, where PREDRAWN is set, or for requesters with NOREQBACKFILL 
set, this variable is ignored. 

Req Layer 

While the requester is active, this contains the address of the Layer structure used in rendering the 
requester. 

ImageBMap 

A pointer to the custom bitmap for this requester. If this requester is not PREDRAWN, Intuition ignores this 
variable. 

When a custom bitmap is supplied, the PREDRAWN flag in the requester's Flags field must be set. 

RWindow 

Reserved for system use. 

Reqlmage 

A pointer to a list of Image structures used to create imagery within the requester. Intuition ignores this field 
if the flag USEREQIMAGE is not set. This imagery is automatically redrawn by Intuition each time the 
requester needs refreshing. The images are drawn after filling with the BackFill pen, but before the 
gadgets and text. 

ReqPadl, ReqPad2 

Reserved for system use. 
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Easy Requesters 

EasyRequest() provides a simple way to make a requester that allows the user to select one of a limited number of 
choices. (A similar function, AutoRequest(), is also available but is not as flexible or as powerful. See the Amiga 
ROM Kernel Reference Manual: Includes and Autodocs for more information.) 
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Figure 7-2: A Simple Requester Made with EasyRequest() 

The program supplies the text for the body of the requester, text for each of the possible options, an optional title for 
the window, and other arguments. The body text can consist of one or more lines with lines separated by the linefeed 
character. 

Each option for an easy requester is displayed as a simple button gadget positioned beneath the body text you 
specify. The layout of the requester, its text and buttons, is done automatically and is font sensitive. The screen font 
(Screen. Font) is used for all text in the requester. 

Typically, easy requesters have one selection indicating a positive action and one selection indicating a negative 
action. The text used for the positive action might be "OK", "Yes," "True," "Retry," or similar responses. Likewise, the 
text used for the negative action might be "No," "False," "Cancel," and so on. The negative choice should always be 
the rightmost or final choice and will return a zero if selected. 

When EasyRequestQ is called, Intuition will build the requester, display it, and wait for user response. 



LONG EasyRequest ( struct Window *window, struct EasyStruct 
ULONG *idcmpPtr, APTR argl, ... ) ; 



•■easyStruct 



LONG EasyRequestArgst struct Window *window, struct EasyStruct *easyStruct, 
ULONG *idcmpPtr, APTR ergs ) ; 

The window argument is a pointer to the reference window. The requester will be displayed on the same screen that 
the reference window is on and also takes its title from the reference window, if not otherwise specified. This 
argument can be NULL, which means the requester is to appear on the Workbench screen, 
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The easyStruct argument is a pointer to an EasyStruct structure which defines the setup and the text of this easy 
requester (described below). 

The idcmpPtr argument is a pointer to a ULONG containing the IDCMP flags for the event that you want to terminate 
this requester. If such an event occurs the requester is terminated (with a result of -1) and the ULONG that idcmpPtr 
points to will contain the actual class of the event message. This feature allows external events to satisfy the request, 
such as the user inserting a disk in the disk drive. This argument can be set to NULL for no automatic termination. 

The gadget and body text for an easy requester is specified in an EasyStruct structure (see below). Body text can be 
specified using a printfQ-style format string that also accepts variables as part of the text. If variables are specified in 



the requester text, their value is taken from the ergs (or argl,...) parameters shown in the prototypes above. 
EasyRequestArgs() takes a pointer to an array of pointers to arguments, while EasyRequestQ has a varargs 
interface and takes individual arguments as part of the function call. The types of these arguments are specified in the 
format strings of the EasyStruct structure. Arguments for es_GadgetFormat follow arguments for es_TextFormat. 

The EasyRequest() functions return an integer from to n - 1 , where n is the number of choices specified for the 
requester. The numbering from left-to-right is: 1 , 2, ..., n - 1,0. This is for compatibility with AutoRequest() which 
returns FALSE for the rightmost gadget. 

The function will return -1 if it receives an IDCMP event that matches one of the termination events specified in the 
idcmpPtr argument. 

Turn Off the Verify Messages. Use ModifylDCMP() to turn off all verify messages (such 
as MENUVERIFY) before calling EasyRequest() or AutoRequest(). Neglecting to do so 
can cause situations where Intuition is waiting for the return of a message that the 
application program cannot receive because its input is shut off while the requester is up. 
If Intuition finds itself in a deadlock state, the verify function will timeout and will be 
automatically replied. 

THE EASYSTRUCT STRUCTURE 

The text and setup of an easy requester is specified in an EasyStruct structure, defined in <intuition/intuition.h>. 

struct EasyStruct 

{ 

ULONG es_StructSize; 

ULONG es_Flags; 

UBYTE *es_Title; 

UBYTE *es_TextFormat; 

UBYTE *es_GadgetFormat; 
} ; 

es_StructSize 

Contains the size of the EasyStruct structure, sizeof(struct EasyStruct). 

es_Flags 

Set to zero. 

es_Title 

Title of easy requester window. If this is NULL, the title will be taken to be the same as the title of the 
reference window, if one is specified in the EasyRequest() call, else the title will be "System Request". 
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es_TextFormat 

Format string for the text in the requester body, with printf()-style variable substitution as described in, the 
Exec library function RawDoFmt(). Multiple lines are separated by the linefeed character (hex OxOa or '\n' 
in C). Formatting '%' functions are supported exactly as in RawDoFmt(). The variables that get substituted 
in the format string come from the last argument passed to EasyRequest() (see prototype above). 

es_GadgetFormat 

Format string for gadgets, where the text for separate gadgets is separated by T (vertical bar). As with the 
body text, printf()-style formatting with variable substitution is supported, but multi-line text in the gadgets 
is not supported. At least one gadget must be specified. 

Requesters generated with EasyRequestQ and BuildEasyRequestQ (including system requesters, which use 
SysReqHandler() to handle input) can be satisfied by the user via the keyboard. The key strokes left Amiga V and 
left Amiga B correspond to selecting the requester's leftmost or rightmost gadgets with the mouse, respectively. 



An easy request must have at least one choice. Multiple choices are specified through the "|" (vertical bar) separator 
character in the es_GadgetFormat string. The buttons are displayed evenly spaced, from left-to-right in the order in 
which they appear in the string. 

The requesters generated by EasyRequest() appear in the visible portion of the specified screen. They do not cause 
the screen to scroll. Under the current implementation, the window for an easy requester will appear in the upper left 
corner of the display clip for the specified screen. 

When a request is posted using EasyRequest() or BuildEasyRequestQ, it will move the screen it appears on to the 
front, if that screen is not already the frontmost. This brings the request to the attention of the user. The request also 
comes up as the active window and could potentially steal the input focus from the current window. 

When the request is satisfied the screen will be moved to back if the request caused the screen to move to the front 
when it was displayed. Note that the final screen position may not be the same as the original screen position. 

Example Using EasyRequest 

;/* easyrequest . c - Execute me to compile me with SAS C 5.10 

LC -bl -cfistq -v -y -j73 easyrequest . c 

Blink FROM LIB : c . o, easyrequest . o TO easyrequest LIBRARY LIB :LC . lib, LIB : Amiga . lib 

quit 

** easyrequest . c - show the use of an easy requester. 

*/ 

#define INTUI_V3 6_NAMES_ONLY 

#include <exec/types .h> 
#include <intuition/intuition.h> 

#include <clib/exec_protos . h> 
#include <clib/intuition_protos .h> 

#include <stdio.h> 

#ifdef LATTICE 

int CXBRK(void) { return(O); } /* Disable Lattice CTRL/C handling */ 

int chkabort (void) { return(O); } /* really */ 

#endif 

/* declare the easy request structure. 

** this uses many features of EasyRequest () , including: 

** multiple lines of body text separated by ' \n' . 

** variable substitution of a string (%s) in the body text. 

** multiple button gadgets separated by ' | ' . 

** variable substitution in a gadget (long decimal ' %ld' ) . 

*/ 

struct EasyStruct myES = 

{ 

sizeof (struct EasyStruct), 

0, 

"Request Window Name", 

"Text for the request\nSecond line of %s text\nThird line of text for the 
request" , 

"Yes | %ld|No", 

}; 

struct Library *IntuitionBase; 

/* 

** Main routine to show the use of EasyRequest ( ) 



*/ 

VOID main (int argc, char **argv) 

{ 

LONG answer; 

LONG number; 

number = 3125794; /* for use in the middle button */ 

if (IntuitionBase = OpenLibrary ( "intuition. library" , 37) ) 

{ 

/* note in the variable substitution: 

** the string goes in the first open variable (in body text) . 

** the number goes in the second open (gadget text) . 

*/ 

answer = EasyRequest (NULL, &myES, NULL, "(Variable)", number); 

/* Process the answer. Note that the buttons are numbered in 

** a strange order. This is because the rightmost button is 

** always a negative reply. The code can use this if it chooses, 

** with a construct like: 

* * 

** if (EasyRequest () ) 

** positive_response ( ) ; 

*/ 

switch (answer) 

{ 

case 1 : 

printf ( "selected 'Yes'\n"); 
break; 

case 2 : 

printf ( "selected ' %ld' \n" , numbers- 
break; 

case : 

printf ( "selected 'No'\n"); 
break; 

} 

CloseLibrary (IntuitionBase) ; 
} 
} 

LOW LEVEL ACCESS TO EASY REQUESTERS 

The EasyRequest() function calls a lower level Intuition function named BuildEasyRequestQ to construct the 
requester. An application can call BuildEasyRequest() directly if it needs to use an easy requester but requires 
custom handling of the events sent to the requester. Handling of the events should be done using the 
SysReqHandler() function as described below. 
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The BuildEasyRequest() functions take the same arguments as EasyRequest(): 

struct Window *BulldEasyRequestArgs ( struct Window *window, 

struct EasyStruct *easyStruct, unsigned long ldcmp, APTR ergs ); 

struct Window *BulldEasyRequest ( struct Window *window, 

struct EasyStruct *easyStruct, unsigned long idcmp, APTR argl, ... ) ; 

To process input event information directly while an easy requester is displayed, first call BuildEasyRequest() then 



call SysReqHandler() periodically to process user input. 

LONG SysReqHandler ( struct Window *window, ULONG *ldcmpPtr, long waitlnput ); 

This will provide standard handling of events but allow the application to control the timing of checking the events. 
This handling includes checks for left Amiga keys. 

The FreeSysRequest() function must be called after an application has finished with a requester (if it was created 
with BuildEasyRequest() call). 

void FreeSysRequest ( struct Window *window ) ; 

This function ends the requester and frees any resources allocated with the BuildEasyRequestQ call. 



System Requesters 



System requesters, such as DOS requests to "Insert volume foo in any drive," are created by the system using 
EasyRequest(). Unless otherwise specified, these requests appear on the default public screen. 

System requests may appear at any time the system requires a resource that is not available. The user may be in the 
middle of an action, the program may be in any state. 

Use the function ModifylDCMPQ to turn off all verify messages before calling any function that might generate a 
system requester. Neglecting to do so can cause situations where Intuition is waiting for the return of a message 
which the application program is unable to receive because its input is shut off while the requester is up. If Intuition 
finds itself in a deadlock state, the verify function will timeout and be automatically replied. 

REDIRECTING SYSTEM REQUESTERS 

A process can force the system requests which are caused by its actions to appear on a custom screen by changing 
the pr_WindowPtr field of its Process structure. This field may be set to three values: zero, negative one or a valid 
pointer to the Window structure of an open window. If pr_WindowPtr is set to zero, the request will appear on the 
default public screen. If pr_WindowPtr is set to negative one, the system request will never appear and the return 
code will be as if the user had selected the rightmost button (negative response). If pr_WindowPtr is set to a valid 
window pointer, then the request will appear on the same screen as the window. 

The original virtue of pr_WindowPtr should he cached and restored before the window is closed. 

Intuition Requesters and Alerts 219 

Alerts 

Alerts are for emergency messages. They cam he displayed oven when the system is in a very fragile state, such as 
when the system is low on memory or when some of the system lists are corrupt. 

Alerts can be displayed by either the system or an application. They are reserved for urgent messages and dire 
warnings in situations that require the user to take some immediate action. Alerts should only be used where no other 
display type is possible. For instance, when the system has crashed or is about to crash, an alert could be used to 
inform the user of the cause. 

The sudden display of an alert is a jarring experience for the user. The system stops dead while the alert is displayed 
and waits for the user input. For this reason, alerts should only be used when there is no recourse. If possible, use 
requesters or windows to display warning messages in place of alerts. 

System alerts are managed entirely by Intuition. The program does not have to take any action to invoke or process 
these alerts. Alerts do not have access to the display database or other information required to open in specialized 
display modes. For this reason, alerts must appear in a display mode available on all machines, namely high 



resolution, non-interlaced. Alerts do not use overscan, so the display is limited to 640 by 200 on an NTSC machine, 
and 640 by 256 on a PAL machine. 

The alert appears at the top of the video display. They are displayed the full 640 pixels wide and as tall as needed, up 
to the limits described above. Alerts are always displayed on a black background. The text of the alert is displayed 
within a rectangular border. Both the text and the border are displayed in a single color which is determined by the 
type of the alert. 

The user responds to an alert by pressing one of the mouse buttons. The left mouse button signifies a positive 
response such as "Retry" or "OK". The right mouse button signifies a negative response such as "Cancel" or "Abort". 

Alerts Save Up User Input The events produced by the user during an alert are not 
consumed by the alert. These events are passed through to the program when the alert 
returns. There could be a great deal of input queued and waiting for processing by the 
application. 

TYPES OF ALERTS 

There are two levels of severity for alerts: 

RECOVERY_ALERT 

Recovery alerts are used in situations where the caller believes that the system can resume operations 
after handling the error. The alert is used as a warning, and is displayed in amber. 

A recoverable alert displays the text of the alert and flashes the border while waiting for the user to 
respond. It returns TRUE if the user presses the left mouse button in response to the alert, otherwise 
FALSE is returned. 

DEADEND_ALERT 

Deadend alerts are used in situations where the caller believes that no recovery from the error is possible, 
and further operation of the system is impossible. This alert is used to inform the user of a fatal problem 
and is displayed in red. Deadend alerts are the same as recoverable alerts in every way except color. 
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CREATING ALERTS 

The function Display Alert() creates and displays an alert message. The message will almost always be displayed 
regardless of the state of the machine (with the exception of catastrophic hardware failures). If the user presses one 
of the mouse buttons, the display is restored to its original state, if possible. If a recoverable alert cannot be displayed 
(because memory is low), DisplayAlertQ will return FALSE, as if the user had selected cancel. DisplayAlert() is also 
used by the system to display the Amiga system alert messages. 

BOOL DlsplayAlert ( unsigned long alertNumber, UBYTE *string, unsigned long height ) ; 

The alertNumber argument is a LONG value, specifying whether this is a RECOVERYALERT or a 
DEADEND_ALERT (see the <intuition/intuition.h> include file). 

The string argument points to a string that is made up of one or more substrings. Each substring contains the 
following: 

The first component is a 16 bit x-coordinate and an 8 bit y-coordinate describing where to position the 
substring within the alert display. The units are in pixels. The y-coordinate describes the location of the text 
baseline. 

The second component is the text itself. The substring must be NULL terminated (it ends with a zero byte). 

The last component is the continuation byte. If this byte is zero, this is the last substring in the message. If 
this byte is non-zero, there is another substring in this alert message. 



The complete string must be terminated by two NULL characters; one as the end of the last substring, and one as a 
NULL continuation byte, indicating that this was the last substring. The height argument is the number of display 
lines required for the alert. 

DISPLAY ALERT EXAMPLE 

This program demonstrates an alert. An explanation of the positioning values for the alert strings is in the comment 
that precedes the alertMsg string. 

;/* displayalert . c - Execute me to compile me with SAS C 5.10 

LC -bl -cfistq -v -y -J73 displayalert . c 

Blink FROM LIB : c . o, displayalert . o TO displayalert LIBRARY LIB : LC . lib, LIB : Amiga . lib 

quit 

** This program demonstrates an alert. An explanation of the positioning 
** values for the alert strings is in the comment that precedes the 
** alertMsg string. 

** displayalert . c - This program implements a recoverable alert 

*/ 

#define INTUI_V3 6_NAMES_ONLY 

#include <exec/types . h> 
#include <intuition/intuition.h> 

#include <clib/exec_protos . h> 
#include <clib/intuition_protos .h> 

#include <stdio.h> 

#ifdef LATTICE 

int CXBRK(void) { return(O); } /* Disable Lattice CTRL/C handling */ 

int chkabort (void) { return(O); } /* really */ 

#endif 

/* Each string requires its own positioning information, as explained 

** in the manual. Hex notation has been used to specify the positions of 

** the text. Hex numbers start with a backslash, an "x" and the characters 

** that make up the number. 

* * 

** Each line needs 2 bytes of X position, and 1 byte of Y position. 

** In our 1st line: x = \x00\xF0 (2 bytes) and y = \xl4 (1 byte) 

** In our 2nd line: x = \x00\xA0 (2 bytes) and y = \x24 (1 byte) 

** Each line is null terminated plus a continuation character (0=done) . 

** This example assumes that the complier will concatenate adjacent 

** strings into a single string with no extra NULLs . The compiler does 

** add the terminating NULL at the end of the entire string... The entire 

** alert must end in TWO NULLs, one for the end of the string, and one 

** for the NULL continuation character. 

*/ 

UBYTE *alertMsg = 

"\x00\xF0\xl4" "OH NO, NOT AGAIN!" "\x00\x01" 

"\x00\x80\x24" "PRESS MOUSEBUTTON: LEFT=TRUE RIGHT=FALSE" "\x00"; 

struct Library *IntuitionBase; 

VOID main (int argc, char **argv) 



{ 

if (IntuitionBase = OpenLibrary ( "intuition. library" , 33 ) 

{ 

if (DisplayAlert (RECOVERY_ALERT, alertMsg, 52)) 

printf ( "Alert returned TRUE\n"); 
else 

printf ( "Alert returned FALSE\n"); 

CloseLibrary (IntuitionBase) ; 
} 



Function Reference 

The following are brief descriptions of tile Intuition functions that relate to the use of Intuition requesters and alerts. 
See the Amiga ROM Kernel Reference Manual: Includes and Autodocs for details on each function call. 

Table 7-1 : Functions for Intuition Requeaters and Alerts 



Function 



Description 



Request() 

EndRequestQ 

InitRequesterQ 



Open a requester in an open window. 
Close an open requester in a window. 
Clear a requester structure before use. 



EasyRequestArgs() 

EasyRequest() 

BuildEasyRequestArgs() 

BuildEasyRequest() 

SysReqHandlerQ 



Open a system requester. 
Alternate calling sequence for EasyRequestArgs(). 
Low level function to open EasyRequestArgsQ. 
Low level function to close EasyRequestArgsQ. 
Event handler function for EasyRequestArgsQ. 



Autonequest() 

BuildSysRequest() 

FreeSysRequestQ 



SetDMRequestf 
ClearDMRequest() 
Display Alert() 



upen a pre-vab system requester. 

Low level function to open an AutoRequest(). 

Low level function to close an AutoRequestQ. 



Set a double menu requester tor an open window. 
Clear a double menu requester from an open window. 
Open an alert on the screen. 
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Chapter 8 

INTUITION IMAGES, LINE 

DRAWING AND TEXT 

Intuition supports two general approaches to creating images, lines, and text in displays: through Intuition library calls 
and through graphics library calls. 

This chapter explains the use of Intuition structures and functions for creating display imagery. The Intuition graphical 
functions provide a high level interface to the graphics library, giving the application quick and easy rendering 
capabilities. As with any high level calls, some power and flexibility is sacrificed in order to provide a simple interface. 

For more flexibility and control over the graphics, the application can directly call functions in the graphics library as 
discussed in the "Graphics Primitives" chapter. Intuition also has additional features for defining custom graphic 
objects. See the "BOOPSI" chapter for more information on these objects. 

Intuition Graphic Objects 

Intuition graphic objects are easy to create and economical to use. There are just three basic types of graphic objects 
you can use yet these three types cover most rendering needs: 



Image 



Border 



Images are graphic objects that can contain any imagery. They consist of a rectangular bitmap that can be 
any size and describes each individual pixel to be displayed. 

Borders are connected lines of any length and number, drawn between an arbitrary series of points. They 
consist of a series of two dimensional coordinates that describe the points between which lines will be 
drawn. 



IntulText 

IntuiText strings are text strings of any length drawn in any font. They consist of a text string and font 
specification that describes the text to be rendered. 

Intuition Images, Line Drawing and Text 223 

Each of these three objects may be chained together with other members of the same type. For instance, many lines 
of text may be rendered as a single object by linking many instances of IntuiText objects together. Only objects of the 
same type may be linked. 

Any of these types can be rendered into any of the Intuition display elements (window, requester, menu etc.). In fact, 
the application can often display the same structure in more than one position or more than one of the elements at 
the same time. 

DISPLAYING IMAGES, BORDERS AND INTUITEXT 

Images, Borders and IntuiText objects may be directly or indirectly rendered into the display by the application. The 
application can draw these objects directly into windows or screens by using one of the functions Drawlmage(), 
DrawBorder() or PrintlText(). The application supplies the appropriate pointer to a Border, Image or IntuiText 
structure as an argument to the function, as well as position information and a pointer to the correct RastPort. These 
rendering functions are discussed in more detail below. 



The application can also draw these objects indirectly by attaching them to a menu, gadget or requester. As Intuition 
places these elements on the display, it also renders the associated graphics. The Requester, Gadget, and 
Menultem structures contain one or more fields reserved for rendering information. See the specific chapters on 
these items for information on attaching graphical objects to them. 

POSITIONING GRAPHIC OBJECTS 

The position of these objects is specified as the sum of two independent components: an external component which 
gives the position of a base reference point for the list of objects, and an internal component which gives the relative 
offset of a specific object to the base reference point. 

The external component is used to position the object list within the display element. For objects drawn indirectly by 
attaching them to a menu, gadget or requester, this is always a point within the menu, gadget or requester (the top 
left corner). 

For objects drawn directly with the Drawlmage(), DrawBorder() or PrintlTextQ functions, specific x and y 
coordinates are provided as arguments that specify an offset within the screen's or window's RastPort at which to 
display the list of objects. 

Each object also has an internal, relative component that is added to the external component described above to 
determine the final position of the object. This allows the application to reuse a graphical object and have it appear 
relative to each object to which it is attached. For example, if the application has numerous gadgets of the same size, 
it can use a single Border structure to draw lines around all the gadgets. When the gadgets are drawn, the base 
position of the lines will be taken from each specific gadget in turn. 



Creating Images 



With an Image structure an application can create graphic objects quickly and easily and display them almost 
anywhere. Images have an additional attribute that makes them even more economical-by changing two simple data 
elements in the Image structure, the color of the image may be changed. 
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Images are rectangular bitmaps which individually define the color of each pixel represented. Images may not be 
masked to allow part of the background to show through. The entire rectangular image is drawn into the target 
element, overwriting any data it may overlap. All bitplanes defined in the target RastPort within the image's rectangle 
are overwritten either with image data, ones or zeros. 

Images may be directly drawn by the application by using the DrawlmageQ function, described below. The image 
may be rendered into any screen or window RastPort with this function. (DrawlmageStateQ can also be used to 
draw the image, but this is an advanced topic discussed later in the "BOOPSI" chapter. 

The visual imagery for an Image can be removed from the display by calling Eraselmage(). For a normal Image 
structure, this will call the graphics function EraseRectQ, which clears the Image rectangle by using the layer's 
backfill pen to overwrite it. 

Alternately, images can be used indirectly by attaching them to menus, gadgets or requesters when they are 
initialized. For instance, in menus the Menultem structure has the ItemFill and SelectFill fields. If the ITEMTEXT flag 
is cleared and the HIGHIMAGE flag is set, the application may place a pointer to a list of Image structures in each of 
these fields. The system will display the ItemFill images when the menu item is not selected and the SelectFill 
images when the menu item is selected. The application does not have to take any specific action to display these 
images. Once the menus have been added to a window, their management and display is under Intuition control. 

The number of bitplanes in an image does not have to match the number of bitplanes in the display element in which 
the image is rendered. This provides great flexibility in using Image structures, as the same image may be reused in 
many places. 

If the application's window is on the Workbench or some other public screen, it must use caution with hard-coded or 



constant image data, as the color palette of that screen is subject to change. If the application has its own custom 
screen, and it is appropriate for the colors of that screen to change, the same situation arises. Starting with V36, 
Intuition allows the screen opener to provide a mapping of pen number and rendering functions. For example, pens 
are specified for the bright and dark edges of three dimensional objects. Applications can obtain this mapping from 
the Drawlnfo structure. See the "Intuition Screens" chapter for more information on Drawlnfo and the new 3D look of 
Intuition in Release 2. 

A suitably designed image may be drawn into a screen or window of any depth. To accomplish this, the application 
must ensure that detail is not last when the image is displayed in a single bitplane RastPort where only the first 
bitplane of image data will be displayed. This is important if the image will ever be displayed on the Workbench 
screen or any other public screen. 

IMAGE STRUCTURE 

For images, the application must create one or more instances of the Image structure. 

struct Image 

{ 

WORD LeftEdge; 

WORD TopEdge; 

WORD Height; 

WORD Depth; 

UWORD * ImageData; 

UBYTE PlanePick, PlaneOnOff; 

struct Image Next Image;- 
} ; 
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The meanings of the fields in the Image structure are: 

LeftEdge, TopEdge 

The location of the image relative to its base position when it is drawn. These offsets are added to the base 
position to determine the final location of the image data. 

The base position for images rendered with Drawlmage() is taken from arguments passed in the function 
call. For gadgets and menus, the base position is always the upper, left comer of the select box. For 
requesters the base position is always the upper, left comer of the requester. 

Negative values of LeftEdge and TopEdge move the position up and to the left of the base position. 
Positive values move down and to the right. 

Width, Height 

The width and height of the image. Width contains the actual width of the image in pixels. Height specifies 
the height of the image in pixels. 

The Width field of the Image structure contains the actual width in pixels of the widest part of the image, 
not how many pixels are contained in the words that define the image. 



Depth 



The depth of the image, or the number of bitplanes used to define it. This is not the depth of the screen or 
window in which the image will be displayed, it is the actual number of bitplanes that are defined in the 
ImageData. 



ImageData 

This is a pointer to the bits that define the image and determine the colors of each pixel. Image data must 
be placed in Chip memory. The data is organized as an array of 16 bit words whose size can be computed 
as follows: 

WordWidth = (Width + 16) / 16) ; 



NumlmageWords = WordWidth * Height * Depth; 

The width of the image is rounded up to the nearest word (16 bits) and extra trailing bits are ignored. Each 
line of each bitplane must have enough words to contain the image width, with extra bits at the end of each 
line set to zero. For example, an image 7 bits wide requires one word for each line in the bitplane, whereas 
an image 17 bits wide requires two words for each line in the bitplane. 

PlanePick 

PlanePick tells which planes of the target BitMap are to receive planes of image data. This field is a 
bit-wise representation of bitplane numbers. For each bit set in PlanePick, there should be a 
corresponding bitplane in the image data. 

PlaneOnOff 

PlaneOnOff tells whether to set or clear bits in the planes in the target BitMap that receive no image data. 
This field is a bit-wise representation of bitplane numbers. 

Nextlmage 

This field is a pointer to another instance of an Image structure. Set this field to NULL if this is the last 
Image structure in the linked list. 
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DIRECTLY DRAWING THE IMAGE 

As noted above, you use the Drawlmage() call to directly draw an image into a screen or window RastPort. 

void Drawl mage( struct RastPort *rp, struct I mage*image, long leftOffset, long topOffset ); 

The rp argument is a pointer to the RastPort into which the image should be drawn. This RastPort may come from a 
Window or Screen structure. 

The image argument is a pointer to the list of Image structures that are to be rendered. The list may contain a single 
Image structure. 

The leftOffset and topOffset arguments are the external component, or the base position, for this list of images. The 
LeftEdge and TopEdge values of each Image structure are added to these values to determine the final position of 
each image. 

Images may also be indirectly drawn by attaching them to gadgets, menus or requesters when they are initialized. 

IMAGE DATA 

Image data must be in Chip memory. The Image structure itself may be in any memory, but the actual data 
referenced by ImageData field must be in Chip memory. This may be done by using compiler specific options, such 

as the chip keyword of SAS/C, or by allocating memory with the MEMF_CHIP attribute and copying the image data 

to that memory. 

Defining Image Data 

Image data consists of binary data organized into a series of 16-bit words. The words must be sequential where each 
successive word represents bits that are displayed later in the image. The image is defined as follows: 

The image is broken down into bitplanes. Each bitplane is considered separately. 

Within a single bitplane, each row of pixels is taken separately. First, round the number of pixels up to the 
next even multiple of 16. This determines the number of words used to represent a single row of data. For 
instance, an image that is 17 bits wide will require two 16-bit words to represent each row. 

The leftmost 16 pixel values are placed in the first word, followed by the next 16 pixel values, and so on. Any 



extra pixels at the end of the last word of the ImageData should be set to zero. 

The first row of data is the topmost row of the low order bitplane. This is immediately followed by the second 
row, then the third, until all rows in the bitplane have been represented. 

The data for the low order bitplane is followed immediately by the next to lowest, then the next, etc. 

The color of each pixel in the image is directly related to the value in one or more memory bits, depending upon how 
many bitplanes there are in the image data and in which bitplanes of the screen or window the display is displayed. 
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The calm a single pixel may Be determined by combining free bits taken from the same receive position within each 
of the bitplanes used to define the image. For each pixel, the system combines all the bits in the same position to 
create a binary value that corresponds to one of the system color registers. This method of determining pixel color is 
called color indirection, because the actual color value is not in the display memory. Instead, it is in color registers 
that are located somewhere else in memory. 

In many situations, the image and display will have different number of bitplanes, which complicates the 
determination of the color value for a given pixel. For now, assume that the image and display have the same number 
of bitplanes. The more complex example will be covered below, in the section "Picking Bitplanes for the Image 
Display". 

If an image consists of only one bitplane and is displayed in a one bitplane display, then wherever there is a O bit in 
the image data, the color in color register zero is displayed and wherever there is a 1 bit, the color in color register 
one is displayed. 

In an image composed of two bitplanes, the color of each pixel is obtained from a binary number formed by the 
values in two bits, one from the first bitplane and one from the second bitplane. If the bit in the first bitplane is a 1 and 
the bit in the second bitplane is a 0, then the color of that pixel will be taken from color An, register two (since 1 in 
binary is two in decimal). Again, the first bitplane describes all of the low order bits for each pixel. The second bitplane 
describes the next higher bit, and so on. This can be extended to any number of bitplanes. 

Image Data Hexadecimal Representation 



************************i 
************************* 



FFFF FF00 

C000 0300 

C000 0300 

C000 0300 

C000 0300 

C000 0300 

C000 0300 

C000 0300 

C000 0300 

FFFF FF00 



Figure 6-1 : Rendering of the Following Example Image 

/* simpleimage . c - program to show the use of a simple Intuition Image. 



* * 



** compiled with: 

** lc -bl -cfist -v -y simpleimage . c 

** blink FROM LIB :c.o+" simpleimage .o" TO "simpleimage" LIB LIB :1c. lib LIB:amiga. lib 

*/ 

#define INTUI_V3 6_NAMES_ONLY 

#include <exec/types . h> 
#include <intuition/intuition.h> 
#include <intuition/intuitionbase .h> 



#include <clib/exec_protos . h> 
#include <clib/dos_protos .h> 
#include <clib/intuition_protos .h> 

#include <stdio.h> 



#ifdef LATTICE 
int CXBRK(void) 
int chkabort (void) 
#endif 



return(O) ; } /* Disable Lattice CTRL/C handling */ 
return (0) ; } /* really */ 



struct IntuitionBase *IntuitionBase 



NULL ; 



#define MYIMAGE_LEFT (0) 

ttdefine MYIMAGE_TOP (0) 

#define MYIMAGE_WIDTH (24) 

#define MYIMAGE_HEIGHT (10) 

#define MYIMAGE DEPTH (1) 



/* This is the image data. It is a one bit-plane open rectangle which is 24 

** pixels wide and 10 high. Make sure that it is in CHIP memory, or allocate 

** a block of chip memory with a call like this: AllocMem(data_size, MEMF_CHIP) 

** and then copy the data to that block. See the Exec chapter on Memory 

** Allocation for more information on AllocMemO . 

*/ 

UWORD chip mylmageData [] = 



{ 

OxFFFF, 
OxCOOO, 
OxCOOO, 
OxCOOO, 
OxCOOO, 
OxCOOO, 
OxCOOO, 
OxCOOO, 
OxCOOO, 
OxFFFF, 

}; 



OxFFOO, 
0x0300, 
0x0300, 
0x0300, 
0x0300, 
0x0300, 
0x0300, 
0x0300, 
0x0300, 
OxFFOO, 



/* 

** main routine. Open required library and window and draw the images. 

** This routine opens a very simple window with no IDCMP . See the 

** chapters on "Windows" and "Input and Output Methods" for more info. 

** Free all resources when done. 



*/ 

VOID main (int argc, char *argv[]) 



{ 

struct Window *win; 
struct Image mylmage; 

IntuitionBase = (struct IntuitionBase *) OpenLibrary ( "intuition. library" , 37) 
if (IntuitionBase != NULL) 



if (NULL 



{ 



OpenWindowTags (NULL, 
WA_Width, 2 00, 
WA_Height, 100, 
WA_RMBTrap , TRUE , 
TAG END) ) ) 



mylmage . Lef tEdge 



MYIMAGE LEFT; 



mylmage . TopEdge 
mylmage . Width 
mylmage . Height 
mylmage . Depth 
mylmage . ImageData 
mylmage . PlanePick 
mylmage . PlaneOnOf f 
mylmage . Next Image 



MYIMAGE_TOP; 

MYIMAGE_WIDTH; 

MYIMAGE_HEIGHT; 

MYIMAGE_DEPTH; 

mylmageData ; 

Oxl; 

0x0; 

NULL ; 



/* use first bit-plane */ 
/* clear all unused planes */ 



} 



/* Draw the 1 bit-plane image into the first bit-plane (color 1) */ 
Drawlmage (win->RPort , &my Image, 10,10) ; 

/* Draw the same image at a new location */ 
Drawlmage (win- >RPort , &mylmage ,100,10) ; 

/* Wait a bit, then quit. 

** In a real application, this would be an event loop, like the 

** one described in the Intuition Input and Output Methods chapter. 

*/ 

Delay (200) ; 

CloseWindow (win) ; 

} 
CloseLibrary ( (struct Library *) IntuitionBase) ; 

} 



PICKING BITPLANES FOR IMAGE DISPLAY 



A single image may be displayed in different colors without changing the underlying image data. This is done by 
selecting which of the target bitplanes are to receive the image data, and what to do with the target bitplanes that do 
not receive any image data. 

PlanePick and PlaneOnOff are used to control the bitplane rendering of the image. The bits in each of these 
variables have a direct correspondence to the bitplanes of the target bitmap. The lowest bit position corresponds to 
the lowest numbered bitplane, the next highest bit position corresponds to the next bitplane, etc. 

For example, for a window or screen with three bitplanes (consisting of planes 0, 1 , and 2), all the possible values for 
PlanePick or PlaneOnOff and the planes picked are as follows: 



PlanePick or 




PlaneOnOff 


Planes Picked 


000 


No planes 


001 


Plane 


010 


Plane 1 


011 


Planes and 1 


100 


Plane 2 


101 


Planes and 2 


110 


Planes 1 and 2 


111 


Planes 0, 1,and2 



PlanePick picks the bitplanes of the containing RastPort that will receive the bitplanes of the image. For each plane 
that is picked to receive data, the next successive plane of image data is drawn there. For example, if an image with 
two bitplanes is drawn into a window with four bitplanes with a PlanePick of binary 1010, the first bitplane of the 
image will be drawn into the second bitplane of the window and the second bitplane of the image will be drawn into 
the fourth bitplane of the window. Do not set more bits in PlanePick than there are bitplanes in the image data. 

PlaneOnOff specifies what to do with the bitplanes that are not picked to receive image data. If the PlaneOnOff bit is 
zero, then the associated bitplane will be filled with zeros. If the PlaneOnOff bit is one, then the associated bitplane 



will be filled with ones. Of course, only bits that fall within the rectangle defined by the image are affected by this 
manipulation. 

Only the bits not set in PlanePick are used in PlaneOnOff, that is, PlaneOnOff only applies to those bitplanes not 
picked to receive image data. For example, if PlanePick is 1010 and PlaneOnOff is 1 100, then PlaneOnOff may be 
viewed as x1x0 (where the x positions are not taken into consideration). In this case, planes two and four would 
receive image data and planes one and three would be set by PlaneOnOff. Each bit in plane one would be set to 
zero and each bit in plane three would be set to one. 

PlaneOnOff is only useful where an entire bitplane of an image may be set to the same value. If the bitplane is not all 
set to the same value, even for just a few bits, then image data must be specified for that plane. 
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A simple trick to create a filled rectangle of any color may be used by supplying no image data, where the color is 
controlled by PlaneOnOff. The Depth of such an image is set to zero, the size of the rectangle is specified in the 
Width and Height fields and the ImageData pointer may be NULL. PlanePick should be set to zero, as there are no 
planes of image data to pick. PlaneOnOff is then set to the color register which contains the desired color for the 
rectangle. 

IMAGE EXAMPLE 

A more complex example of the use of an Image is presented below. 

Plane 0, Open Rectangle 



************************* 
************************* 



Plane 1, Filled Rectangle 



•OOOOOOOO" 

»oooooooo« 

•OOOOOOOO" 
•OOOOOOOO" 



3 -Color Combined Image 

**•••••• oooooooo ••••••**•••••••• 

**•••••• oooooooo ••••••**•••••••• 

**•••••• oooooooo ••••••**•••••••• 

**•••••• oooooooo ••••••**•••••••• 



Figure 8-2: Picture of the More Complex Example Image 
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/* compleximage . c - program to show the use of a complex Intuition Image. 
* * 

** compiled with: 

** lc -bl -cfist -v -y compleximage . c 

** blink FROM LIB:c.o compleximage . o TO compleximage LIB LIB :1c. lib LIB:amiga. lib 

*/ 

#define INTUI_V3 6_NAMES_ONLY 

#include <exec/types . h> 
#include <intuition/ intuition. h> 
#include <intuition/intuitionbase . h> 

#include <clib/exec_protos . h> 
#include <clib/dos_protos .h> 
#include <clib/intuition_protos .h> 

#include <stdio.h> 

#ifdef LATTICE 

int CXBRK(void) { return(O); } /* Disable Lattice CTRL/C handling */ 

int chkabort (void) { return(O); } /* really */ 

#endif 

struct IntuitionBase *IntuitionBase = NULL; 

#define MYIMAGE_LEFT (0) 

#define MYIMAGE_TOP (0) 

#define MYIMAGE_WIDTH (24) 

#define MYIMAGE_HEIGHT (10) 

#define MYIMAGE_DEPTH (2) 

/* This is the image data. It is a two bitplane open rectangle which 

** is 24 pixels wide and 10 high. Make sure that it is in CHIP memory, 

** or allocate a block of chip memory with a call like: 
** 

** AllocMem(data_size,MEMF_CHIP) 
** 

** and copy the data to that block. See the Exec chapter on 
** Memory Allocation for more information on AllocMem() . 
*/ 



UWORD chip mylmageData [] = 

{ 

/* first bitplane of data, 

** open rectangle. 

*/ 

OxFFFF, OxFFOO, 

OxCOOO, 0x0300, 

OxCOOO, 0x0300, 

OxCOOO, 0x0300, 

OxCOOO, 0x0300, 

OxCOOO, 0x0300, 

OxCOOO, 0x0300, 

OxCOOO, 0x0300, 

OxCOOO, 0x0300, 

OxFFFF, OxFFOO, 

/* second bitplane of data, 

** filled rectangle to appear within open rectangle. 

*/ 

0x0000, 0x0000, 

0x0000, 0x0000, 

0x0000, 0x0000, 

OxOOFF, 0x0000, 

OxOOFF, 0x0000, 

OxOOFF, 0x0000, 

OxOOFF, 0x0000, 

0x0000, 0x0000, 

0x0000, 0x0000, 

0x0000, 0x0000, 

}; 

/* used to get the "new look" on a custom screen */ 
UWORD pens [] = { ~0 } ; 

/* 

** main routine. Open required library and window and draw the images. 

** This routine opens a very simple window with no IDCMP . See the 

** chapters on "Windows" and "Input and Output Methods" for more info. 

** Free all resources when done. 

*/ 

VOID main(int argc, char *argv[]) 

{ 

struct Screen *scr; 
struct Window *win; 
struct Image mylmage; 

IntuitionBase = (struct IntuitionBase *) OpenLibrary ( "intuition. library" , 37) 
if (IntuitionBase != NULL) 

{ 

if (NULL != (scr = OpenScreenTags (NULL, 

SA_Depth, 4, 

SA_Pens , &pens , 

TAG_END) ) ) 

{ 

if (NULL != (win = OpenWindowTags (NULL, 

WA_RMBTrap , TRUE , 
WA_CustomScreen, scr, 
TAG_END) ) ) 

{ 

mylmage. LeftEdge = MYIMAGE_LEFT; 



mylmage . TopEdge = MYIMAGE_TOP; 

mylmage. Width = MYIMAGE_WIDTH; 

mylmage. Height = MYIMAGE_HEIGHT; 

mylmage . Depth = MYIMAGE_DEPTH; 

mylmage . ImageData = mylmageData; 

mylmage . PlanePick = 0x3; /* use first two bitplanes */ 

mylmage . PlaneOnOff = 0x0; /* clear all unused planes */ 

mylmage .Next Image = NULL; 

/* Draw the image into the first two bitplanes */ 
Drawlmage (win->RPort , &my Image, 10,10) ; 

/* Draw the same image at a new location */ 
Drawlmage (win->RPort , &my Image, 100,10) ; 

/* Change the image to use the second and fourth bitplanes, 

** PlanePick is 1010 binary or OxA, 

** and draw it again at a different location 

*/ 

mylmage . PlanePick = OxA; 

Drawlmage (win->RPort , &my Image, 10,50) ; 

/* Now set all the bits in the first bitplane with PlaneOnOff. 

** This will make all the bits set in the second bitplane 

** appear as color 3 (0011 binary) , all the bits set in the 

** fourth bitplane appear as color 9 (1001 binary) and all 

** other pixels will be color 1 (0001 binary. If there were 

** any points in the image where both bits were set, they 

** would appear as color 11 (1011 binary) . 

** Draw the image at a different location. 

*/ 

mylmage . PlaneOnOff = 0x1; 

Drawlmage (win->RPort , &my Image, 10 0,50) ; 

/* Wait a bit, then quit. 

** In a real application, this would be an event loop, like the 

** one described in the Intuition Input and Output Methods chapter. 

*/ 

Delay(200) ; 

CloseWindow (win) ; 

} 
CloseScreen (scr) ; 

} 
CloseLibrary ( (struct Library *) IntuitionBase) ; 

} 
} 



Creating Borders 



This data type is called a Border since it was originally used to create border lines around display objects. It is 
actually a general purpose structure for drawing connected lines between any series of points. 

A Border is easier to use than an Image structure. Only the following need be specified to define a border: 

An internal position component which is used in determining the final position of the border. 

A set of coordinate pairs for each vertex. 



A color for the lines. 

One of several drawing modes. 

BORDER STRUCTURE DEFINITION 

To use a border, the application must create one or more instances of the Border structure. Here is the 
specification:- 

struct Border 

{ 

WORD LeftEdge, TopEdge; 

UBYTE FrontPen, BackPen; 

UBYTE DrawMode; 

BYTE Count; 

WORD *XY; 

struct Border *NextBorder ; 

}; 

Here is a brief description of the fields of the Border structure. 

LeftEdge, TopEdge 

These fields are used to determine the position of the Border relative to its base position (the base by is 
the upper left corner for requesters, menus, or gadgets and is specified in the call to DrawBorder() for 
windows and screens). 

FrontPen, BackPen 

These fields contain color registers numbers. FrontPen is the color used to draw the lines. BackPen is 
currently unused. 

DrawMode 

Set the DrawMode field to one of the following: 

JAM1 

Use FrontPen to draw the line. 

COMPLEMENT 

Change the pixels within the lines to their complement color. 
Count 

Specify the number of data points used in this border. Each data point is described by two words of data in 
the XY array. 
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XY 

A pointer to an array of coordinate pairs, one pair for each point. These coordinates are measured relative 
to the position of the border. 

Next Border 

This field is a pointer to another instance of a Border structure. Set this field to NULL if this is the last 
Border structure in the linked list. 

DIRECTLY DRAWING THE BORDERS 

Borders may be directly drawn by the application by calling the function DrawBorder(). 

void DrawBorder ( struct RastPort *rp, struct Border *border, long leftOffset, 
long topOf fset ) ; 



The rp argument is a pointer to the RastPort into which the border should be drawn. This rastport may come from a 
Window or Screen structure. 

The border argument is a pointer to a list of Border structures which are to be rendered. The list may contain a 
single Border structure. 

The leftOffset and topOffset arguments are the external component, or base position, for this list of Borders. The 
LeftEdge and TopEdge values of each Border structure are added to these to determine the Border position. 

Borders may also be indirectly drawn by attaching them to gadgets, menus or requesters. 

BORDER EXAMPLE 

The following example draws a double border using two pens to create a shadow effect. The border is drawn in two 
positions to show the flexibility in positioning borders, note that it could also be attached to a menu, gadget or 
requester. 

;/* shadowborder . c - Execute me to compile me with SAS C 5.10 

LC -bl -cfistq -v -y -J73 shadowborder . c 

Blink FROM LIB : c . o, shadowborder . o TO shadowborder LIBRARY LIB :LC . lib, LIB : Amiga . lib 

quit 

** The following example draws a double border using two pens to create a 

** shadow effect. The border is drawn in two positions to show the 

** flexibility in positioning borders, note that it could also be attached 

** to a menu, gadget or requester. 

* * 

** shadowborder . c - program to show the use of an Intuition Border. 

*/ 

#define INTUI_V3 6_NAMES_ONLY 

#include <exec/types . h> 
#include <intuition/ intuition. h> 

#include <clib/exec_protos . h> 
#include <clib/dos_protos .h> 
#include <clib/intuition_protos .h> 

#include <stdio.h> 

#ifdef LATTICE 

int CXBRK(void) { return(O); } /* Disable Lattice CTRL/C handling */ 

int chkabort (void) { return(O); } /* really */ 

#endif 

struct Library *IntuitionBase = NULL; 

#define MYBORDER_LEFT (0) 
#define MYBORDER_TOP (0) 

/* This is the border data. */ 
WORD myBorderData [] = 

{ 

0,0, 50,0, 50,30, 0,30, 0,0, 

}; 
/* 

** main routine. Open required library and window and draw the images. 



** This routine opens a very simple window with no IDCMP . See the 

** chapters on "Windows" and "Input and Output Methods" for more info. 

** Free all resources when done. 

*/ 

VOID main(int argc, char **argv) 

{ 

struct Screen *screen; 
struct Drawlnfo *drawinfo; 
struct Window *win; 
struct Border shineBorder; 
struct Border shadowBorder; 

ULONG mySHADOWPEN =1; /* set default values for pens */ 
ULONG mySHINEPEN = 2; /* in case can't get info... */ 

IntuitionBase = OpenLibrary ( "intuition. library" , 37) ; 
if (IntuitionBase) 

{ 

if (screen = LockPubScreen (NULL) ) 

{ 

if (drawinfo = GetScreenDrawInfo (screen) ) 

{ 

/* Get a copy of the correct pens for the screen. 

** This is very important in case the user or the 

** application has the pens set in a unusual way. 

*/ 

mySHADOWPEN = drawinf o- >dri_Pens [SHADOWPEN] ; 

mySHINEPEN = drawinf o- >dri_Pens [SHINEPEN] ; 

FreeScreenDrawInfo (screen, drawinfo) ; 

} 
UnlockPubScreen (NULL, screen) ; 

} 

/* open a simple window on the workbench screen for displaying 

** a border. An application would probably never use such a 

** window, but it is useful for demonstrating graphics... 

*/ 

if (win = OpenWindowTags (NULL, 

WA_PubScreen, screen, 

WA_RMBTrap , TRUE , 

TAG_END) ) 

{ 

/* set information specific to the shadow component of the border */ 
shadowBorder .LeftEdge = MYBORDER_LEFT + 1 ; 
shadowBorder .TopEdge = MYBORDER_TOP + 1; 
shadowBorder .FrontPen = mySHADOWPEN; 
shadowBorder .NextBorder = &shineBorder; 

/* set information specific to the shine component of the border */ 
shineBorder .LeftEdge = MYBORDER_LEFT; 
shineBorder .TopEdge = MYBORDER_TOP ; 
shineBorder . FrontPen = mySHINEPEN; 
shineBorder .NextBorder = NULL; 

/* the following attributes are the same for both borders. */ 
shadowBorder .BackPen = shineBorder . BackPen = 0; 
shadowBorder .DrawMode = shineBorder .DrawMode = JAM1; 
shadowBorder . Count = shineBorder . Count = 5; 
shadowBorder .XY = shineBorder .XY = myBorderData; 



/* Draw the border at 10,10 */ 

DrawBorder (win->RPort , &shadowBorder , 10,10) ; 

/* Draw the border again at 100,10 */ 
DrawBorder (win->RPort , kshadowBorder, 100,10) ; 

/* Wait a bit, then quit. 

** In a real application, this would be an event loop, like the 

** one described in the Intuition Input and Output Methods chapter. 

*/ 

Delay (200) ; 

CloseWindow (win) ; 

} 
CloseLibrary (IntuitionBase) ; 

} 
} 

BORDER COLORS AND DRAWING MODES 

Borders can select their colors from the values set in the color registers for the screen in which they are rendered. 
The available number of colors and palette settings are screen attributes and may not be changed through border 
rendering. 

Two drawing modes pertain to border lines: JAM1 and COMPLEMENT. To draw the line in a specific color, use the 
JAM1 draw mode. This mode converts each pixel in the line to the color set in the FrontPen field. 

Selecting the COMPLEMENT draw mode causes the line to be drawn in an exclusive-or mode that inverts the color of 
each pixel within the line. The data bits of the pixel are changed to their binary complement. This complement is 
formed by reversing all bits in the binary representation of the color register number. In a three bitplane display, for 
example, color 6 is 1 10 in binary. In COMPLEMENT draw mode, if a pixel is color 6, it will be changed to the 001 
(binary), which is color 1 . Note that a border drawn in COMPLEMENT mode can be removed from a static display by 
drawing the border again in the same position. 

BORDER COORDINATES 

Intuition draws lines between points that are specified as sets of X, Y coordinates. Border data does not have to be in 
Chip memory. 

The XY field contains a pointer to an array of coordinate pairs. All of these coordinates are offsets relative to the 
Border position, which is determined by the sum of the external and internal position components as described 
above. The coordinate pairs are ordered sequentially. The first two numbers make up the first coordinate pair, the 
next two numbers make up the second pair, and so on. Within a coordinate pair, the first number is the X offset and 
the second number is the Y offset. 

The first coordinate pair describes the starting point of the first line. When the Border is rendered, a line is drawn 
between each pair of points. The first line is drawn from point one to point two, the second line is drawn from point 
two to point three, and so on, until the final point is reached. 

The numbers specified in the XY array may be positive or negative. Negative values move up and to the left relative 
to the Border position, positive values move down and to the right. Again, the Border position is determined by 
adding the external position component and the internal position component. For example, a Border attached to a 
Gadget has an external component equal to the upper left corner of the gadget's select box. The internal component 
is set within the Border structure itself. These two components are added together and offsets from the resulting 
position, specified within the XY array, determine where the lines of the Border will appear. 
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Suppose the top left corner of the select box of the gadget is at window position (10,5). If the Border has LeftEdge 
set to 10 and TopEdge set to 10, then the Border is positioned at (10+10,5+10), that is (20,15). All XY coordinates 
will be relative to this Border position. If the XY array contains '0,5, 15,5, 15,0', then the relative coordinates will be 
(0,5), (1 5,5) and (1 5,0). Adding each coordinate to the Border position gives the absolute position of the lines within 
the window. This Border will draw two lines in the window one from (20,20) to (35,20) and the second from (35,20) to 
(35,15). 
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Figure 8-3: Example of Border Relative Position 

To create a border that is outside the select box of a gadget, specify negative values in the internal component or use 
negative values for the initial XY values. For example, setting LeftEdge to -1 and TopEdge to -1 moves the position 
of the Border one pixel above and one pixel to the left of the gadget's select box. 

LINKING BORDERS 

The NextBorder field can point to another instance of a Border structure. This allows complex graphic objects to be 
created by linking together Border structures, each with its own data points, color and draw mode. This might be 
used, for instance, to draw a double border around a requester or gadget where the outer border is a second Border 
structure, linked to the first inner border. 

Note that the borders can share data. For instance, to create a border with a shadow, link two borders together each 
of which points to the same XY data. Set the first border to draw in a dark pen (such as the SHADOWPEN from the 
screen's Drawlnfo structure) and position the border down and to the right a few pixels by changing LeftEdge and 
TopEdge in the Border structure. 
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The second border should be set to a bright pen (such as the SHINEPEN in the screen's Drawlnfo structure). When 
the border is drawn, the first border will draw in a dark color and then the second border will be drawn over it in a light 
color. Since they use the same data set, and the dark border is shifted down and to the right, the border will have a 
three dimensional appearance. This technique is demonstrated in the example listed earlier in this section. 



Creating Text 



The IntuiText structure provides a simple way of writing text strings within an Intuition display element. These strings 



may be used in windows, screens, menus, gadgets and requesters. To set up an IntuiText, you specify the following: 

Pen colors for the text. 

A draw mode. 

The starting offset for the text. 

The font used to render the text 

The text string to output. 
NTUITEXT STRUCTURE 
To render text using Intuition, the application must create one or more instances of the IntuiText structure: 

struct IntuiText 

{ 

UBYTE Front Pen, BackPen; 

UBYTE DrawMode; 

WORD Left Edge; 

WORD TopEdge; 

struct TextAttr *ITextFont; 

UBYTE * I Text; 

struct IntuiText *NextText, 

}; 

Here is a brief description of each member of the IntuiText structure: 

FrontPen 

The pen number specifying the color used to draw the text. 

BackPen 

The pen number specifying the color used to draw the background for the text, if JAM2 drawing mode is 
specified. 

DrawMode 

This field specifies one of four drawing modes: 

JAM1 

FrontPen is used to draw the text; background color is unchanged. 
JAM2 

FrontPen is used to draw the text; background color is changed to the color in BackPen. 
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COMPLEMENT 

The characters are drawn in the complement of the colors that were in the background. 

INVERSVID 

Inverses the draw modes describe above. For instance INVERVID used with JAM1 means the 
character is untouched while the background is filled with the color of the FrontPen. 

LeftEdge and TopEdge 

The location of the text relative to its base position when it is drawn. These offsets are added to the base 
position to determine the final location of the text data. 

The base position for text rendered with PrintlTextQ is taken from arguments passed in the function call. 
For gadgets and menus, the base position is always the upper, left corner of the select box. For requesters 



the base position is always the upper, left corner of the requester. 

LeftEdge gives the offset of the left edge of the character cell and TopEdge gives the offset of the top 
edge of the character cell for the first character in the text string. Negative values of LeftEdge and 
TopEdge move the position up and to the left of the base position. Positive values move down and to the 
right. 

ITextFont 

A pointer to a TextAttr structure defining the font to be used. Set this to NULL to use the default font. 

IText 

A pointer to the NULL terminated text string to be displayed. 

NextText 

A pointer to another instance of IntuiText. Set this field to NULL for the last IntuiText in a list. 

DIRECTLY DRAWING THE INTUITEXT 

Use the PrintlText() call to directly draw the text into the target RastPort of a window or screen. 

void PrintIText( struct RastPort Warp, struct IntuiText Whitest, long left, long top ) ; 

The rp argument is a pointer to the RastPort into which the text should be drawn. This RastPort can come from a 
Window or Screen structure. 

The iText argument is a pointer to a list of IntuiText structures which are to be rendered. The list may contain a 
single IntuiText structure. If the font is not specified in the IntuiText structure, Intuition will render the text using the 
RastPort's font. 

The left and top arguments give the external component, or base position for this list of IntuiText structures. The 
LeftEdge and TopEdge values in each IntuiText structure are added to these to determine the final position of the 
text. 

IntuiText objects may also be drawn indirectly by attaching them to gadgets, menus or requesters. 
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DETERMINING TEXT LENGTH 

To determine the pixel length of a given IntuiText string, call the lntuiTextLength() function. 

LONG IntuiTextLength ( struct IntuiText *iText ) ; 

Set the iText argument to point to the IntuiText structure whose length is to be found. This function will return the 
length of the iText text string in pixels. Note that if the ITextFont field of the given IntuiText is set to NULL, or Intuition 
cannot access the specified font, then GfxBase->DefaultFont will be used in determining the length of the text This 
may not be the same as the RastPort font with which the text would be printed. 

INTUITEXT EXAMPLE 

;/* intuitext . c - Execute me to compile me with SAS C 5.10 

LC -bl -cfistq -v -y -J73 intuitext . c 

Blink FROM LIB: c.o, intuitext .o TO intuitext LIBRARY LIB : LC . lib, LIB :Amiga . lib 

quit 

** intuitext. c - program to show the use of an Intuition IntuiText object. 

*/ 

#define INTUI V3 6 NAMES ONLY 



#include <exec/types . h> 
#include <intuition/intuition.h> 

#include <clib/exec_protos . h> 
#include <clib/dos_protos . h> 
#include <clib/intuition_protos .h> 

#include <stdio.h> 



#ifdef LATTICE 
int CXBRK(void) 
int chkabort (void) 
#endif 



return(O) ; } /* Disable Lattice CTRL/C handling */ 
return (0) ; } /* really */ 



struct Library *IntuitionBase = NULL; 

ttdefine MYTEXT_LEFT (0) 
#define MYTEXT TOP (0) 



/* 

** main routine. Open required library and window and draw the images. 

** This routine opens a very simple window with no IDCMP . See the 

** chapters on "Windows" and "Input and Output Methods" for more info. 

** Free all resources when done. 

*/ 

VOID main (int argc, char **argv) 

{ 

struct Screen 
struct Drawlnfo 
struct Window 
struct IntuiText 
struct TextAttr 



*screen; 

*drawinfo; 

*win; 

mylText ; 

myTextAttr; 



ULONG myTEXTPEN; 
ULONG myBACKGROUNDPEN; 

IntuitionBase = OpenLibrary ( "intuition. library" , 37) 
if (IntuitionBase) 



if (screen 



LockPubScreen(NULL) ) 



if (drawinfo = GetScreenDrawInfo (screen) ) 

{ 

/* Get a copy of the correct pens for the screen. 

** This is very important in case the user or the 

** application has the pens set in a unusual way. 

*/ 

myTEXTPEN = drawinfo- >dri_Pens [TEXTPEN] ; 

myBACKGROUNDPEN = drawinfo- >dri_Pens [BACKGROUNDPEN] ; 



/* create a TextAttr that matches the specified font. */ 

myTextAttr. ta_Name = drawinfo- >dri_Font->tf_Mes sage .mn_Node . ln_Name; 

myTextAttr . ta_YSize = drawinfo->dri_Font->tf_YSize; 

myTextAttr . ta_Style = drawinfo- >dri_Font- >tf_Style; 

myTextAttr . ta_Flags = drawinfo- >dri_Font->tf_Flags; 



/* open a simple window on the workbench screen for displaying 

** a text string. An application would probably never use such a 

** window, but it is useful for demonstrating graphics... 
*/ 



if (win = OpenWindowTags (NULL, 





WA_ 


PubScreen, screen, 




WA_ 


RMBTrap , TRUE , 


{ 

my I Text . 


TAG 


_END) ) 


. FrontPen 


= myTEXTPEN; 


mylText . 


. BackPen 


= myBACKGROUNDPEN; 


mylText . 


. DrawMode 


= JAM2 ; 


mylText . 


. Lef tEdge 


= MYTEXT_LEFT; 


mylText . 


. TopEdge 


= MYTEXT_TOP; 


mylText . 


. ITextFont 


= &myTextAttr; 


mylText 


. IText 


= "Hello, World. 


mylText . 


. NextText 


= NULL; 



/* Draw the text string at 10,10 */ 
PrintlText (win->RPort, kmylText, 10, 10) ; 

/* Wait a bit, then quit. 

** In a real application, this would be an event loop, 

** like the one described in the Intuition Input and 

** Output Methods chapter. 

*/ 

Delay (200) ; 

CloseWindow (win) ; 

} 
FreeScreenDrawInfo (screen, drawinfo) ; 

} 
UnlockPubScreen (NULL, screen) ; 

} 
CloseLibrary (IntuitionBase) ; 

} 
} 

TEXT COLORS AND DRAWING MODES 

IntuiText gets its colors from the values set in the color registers for the screen in which they are rendered. The 
available number of colors and palette settings are screen attributes and cannot be changed through IntuiText 
rendering. 

Text characters in general are made up of two areas: the character image itself and the background area surrounding 
the character image. The color used in each area is determined by the draw mode which can be set to JAM1 , JAM2 
or COMPLEMENT. The flag INVERSVID may also be specified. 

JAM1 draw mode renders each character with FrontPen and leaves the background area unaffected. Because the 
background of a character is not drawn, the pixels of the destination memory around the character image are not 
disturbed. Graphics beneath the text will be visible in the background area of each character cell. 

JAM2 draw mode renders each character with FrontPen and renders each character background with BackPen. 
Using this mode, any graphics that previously appeared beneath the character cells will be totally overwritten. 
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COMPLEMENT draw mode renders the pixels of each character as the binary complement of the color that is 
currently at the destination pixel. The destination is the display memory where the text is drawn. As with JAM1, 
nothing is drawn into the background. FrontPen and BackPen are not used in COMPLEMENT mode. To determine 
the complement color, invert all the bits in the binary representation of the color register number. The resulting 
number specifies the color register to use for that pixel. In a three bitplane display, for example, color 6 (1 1 in binary) 
is the complement of color I (001 in binary). 



The INVERSVID flag inverses the video for each of the drawing modes. For JAM1 , nothing is drawn into the 
character area and the background is drawn in FrontPen. For JAM2, the character area is drawn in BackPen and 
the background is drawn in FrontPen. For COMPLEMENT mode, nothing is drawn into the character area and the 
background is complemented. 

FONTS 

The application may choose to specify the font used in rendering the IntuiText, or it may choose to use the default 
font for the system. 

To use the default font, set the ITextFont field to NULL. Some care must be taken when using the default font. When 
an IntuiText object is rendered and no font is specified, the text will be rendered in the font set in the RastPort. 

If the RastPort font is NULL, the text will be rendered using GfxBase->DefaultFont. Also, lntuiTextLength() always 
uses GfxBase->DefaultFont when ITextFont is NULL. The application must have open the graphics library in order 
to check the default font in GfxBase. (See the graphics library chapter for more information.) 

To use a specific font for this text, place a pointer to an initialized TextAttr structure in the ITextFont field. Intuition will 
only use the specified font if it is available through a call to the OpenFontQ routine. To use a font from disk, the 
application must first open the font using the OpenDiskFontQ function. For more information about using fonts, see 
the "Graphics Library and Text" chapter in this manual. 

LINKING TEXT STRINGS 

The NextText field can point to another instance of an IntuiText structure. This allows the application to create a 
complex object which has several distinct groups of characters, each with its own color, font, location, and drawing 
mode. This can be used to create multiple lines of text, to position characters in the text very accurately and to 
change the color or font of the text. Each list of IntuiText objects may be drawn with one call to PrintlText(), or 
attached to a gadget, menu or requester as a single object. 
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Function Reference 



The following are brief descriptions of the Intuition functions that relate to the use of graphics under Intuition. See the 
Amiga ROM Kernel Reference Manual: Includes and Autodocs for details on each function call. 

Table 8-1 : Functions for Intuition Drawing Capabilities 



Function 



Description 



DrawBorder() 
Drawlmage() 
PrintlText() 
IntuiTextLengthQ 



Draw a border into a rest port. 
Draw a image into a rest port. 
Draw Intuition text into a rest port 
Find the length of an IntuiText Sting. 



BeginRefresh() 
EndRefreshQ 



Begin optimized rendering after a refresh event. 
End optimized rendering after a refresh event. 



GetScreenDrawlnfo() 
FreeScreenDrawlnfoQ 



Get screen drawing information (V36). 
Free screen drawing information (V36). 
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Chapter 9 

Intuition Input and Output 

Methods 

This chapter discusses the input and output (I/O) techniques used with Intuition. I/O facilities are also available 
through Exec's device subsystems, such as the console, serial and parallel devices. (For more information on these 
see the Amiga ROM Kernel Reference Manual: Devices) 

For graphical output to the Amiga's display, programs can use Intuition's drawing features or handle rendering directly 
through calls to the graphics library. See the three graphics library chapters in this manual for more information on 
display rendering. For more about Intuition's drawing features see the Intuition Images, Line Drawing and Text 
chapter. 

Overview of System I/O 

This section provides a very simplified model of how Amiga I/O and application programs interact. The main 
elements of the Amiga's I/O system are shown in the diagram below. Input events begin when mouse movement is 
detected by the gameport device or key presses are received by the keyboard device. These and other input events 
are merged into a single stream by the input device, which then submits the stream to Intuition for further processing. 
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The application program can receive its input from Intuition or the Console device. The application may choose to 
listen to neither, one or both of these input sources. 




An application's display output can go through the high level interfaces of the console device or through the Intuition 
library. Additionally, display output may be sent directly to the graphics library. Notice that both the Console and 
Intuition call the graphics library to render to the display. 



Intuition Input 



The Amiga has an input device to monitor all input activity. The input activity nominally includes keyboard and mouse 
events, but which can be extended to include other types of input signals. When the user moves the mouse, presses 
a mouse button or types on the keyboard, the input device detects the activity from the specific device, and constructs 
an InputEvent. 

An InputEvent is a message describing a single event, such as the transition of a key on the keyboard from up to 
down. 



The input device then passes the input events down a prioritized chain of input handlers, which are routines in 
memory that process the input events. The sequence of input events passing through this chain of input handlers is 
known as the input stream. Any handler linked into this chain can monitor and modify the event stream. 

Each input handler may block (consume) events, allow events to pass through to the next handler in the chain or add 
new events to the sequence. 

Other devices and programs can add input events to the input stream by sending messages to the input device. For 
instance, AmigaDOS is able to generate an input event whenever a disk is inserted or removed. 

See the Input Device chapter of the Amiga ROM Kernel Reference Manual: Devices for more information on the Input 
device. 
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Intuition as an Input Handler 

Intuition is an input handler linked into the input stream, and it monitors and modifies events that it receives. The 
input arrives at Intuition as a single stream of events. These events are filtered, altered, and enhanced by Intuition, 
then dispatched to windows as appropriate, or passed down to input handlers lower in the chain. If the active window 
has a console attached to it, then it can receive the input events that are still left in the stream, which can include 
some events that Intuition played a role in forming. 



Many kinds of input event undergo little conversion by Intuition. For instance, raw keyboard events are not modified 
by Intuition (with the exception of a few keystrokes that have special meaning). Other events may produce differing 
results based on Intuition's view of the system. For example, when the mouse select button is pressed, the event may 
become a gadget down-press event, a window activation event, or it may remain a simple button press, depending on 
the mouse position and the arrangement of windows and screens. Still other events are consumed by Intuition, and 
the application is not directly notified. An example would be when the select button is pressed over a system gadget. 

Intuition is also the originator of certain kinds of events. For example, a window-refreshing event is generated when 
Intuition discovers that part of a window is in need of redrawing. This might have resulted indirectly from some other 
input (for example, the user might have dragged a window), but not necessarily (the refresh might have been 
necessitated by a program bringing a window to the front). 

Receiving Input Events from Intuition 

There are two channels through which a window can receive events destined for it. The usual way is for the 
application to ask Intuition to send it messages which are based on the input event that Intuition has processed. 
These messages, called IntuiMessages, are standard Amiga Exec messages, and are sent to a port called an 
Intuition Direct Communications Message Port, or IDCMP. Every window may have an IDCMP associated with it 
(pointed to by Window.UserPort). 

There are many classes of IntuiMessages, and the application can control which classes of events are routed to its 
window's port by setting the appropriate IDCMP flags. When Intuition has an event to send, but the window does not 
have the corresponding IDCMP flag set, the event is generally passed along to the next input handler in the chain. 
One input handler that resides below Intuition's is the console device's handler. If your application's window has a 
console attached to it, the console device will generally convert events it receives into console code sequences, and 
send those to your console. In this manner, you can hear these events. 

Because IntuiMessages and the IDCMP are the primary way in which applications receive communication from 
Intuition, discussions elsewhere in the manual frequently refer to events from Intuition as messages, IntuiMessages, 
or IDCMP messages. However, most of the information sent as IntuiMessages is also available through the console 
device, though that option is used less often. Elsewhere in this chapter, you can learn how getting your events 
through the console differs from getting them through your IDCMP. 

Whichever way an application chooses to get its messages, it is frequently designed to be event-driven. That is to 
say, after some amount of initialization, the application will go into a state where it is waiting for some event to 
happen. This event could be an input event, or some other kind of event. Based on the event received, the 
application would take appropriate action, and return to its waiting state. 
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IDCMP Events and the Input Focus 

Although at any given time many applications may be waiting for input, in most cases only the active application (the 
one with the currently active window) will receive IDCMP messages. 

Since the IDCMP messages are, in general, directed to a single window, this window is said to have the input 
focus-the input from a variety of sources is focused on this single location. 

The active window is generally selected by the user, although it is possible for applications to change the active 
window. See the Intuition Windows chapter for information on selecting or setting the active window. Be aware that 
changing the active window will change the input focus. Usually this change is performed following user action--the 
user selects a window with the mouse, or activates a new application. Changes to the input focus without user 
control, such as activating another window while the user is working in an application, may confuse the user. Perform 
such changes with great care. 

Not all events are sent only to the active IDCMP. Some events, such as "disk inserted," may be useful to many 
programs, so Intuition translates these events into separate messages, one for each application. 



Intuition Output 



Visual program output, the information written to the display, is sent through one of three channels. 

Imagery may be sent to the graphics library primitives. Graphics library includes functions for line drawing, 
area fill, specialized animation and output of text. See the graphics library chapters "Graphics Primitives", 
"Graphics Libraries and Text" and "Graphics Sprites, Bobs and Animation" for more on these functions. 

Use the Intuition library support functions for rendering text, graphical imagery, and line drawing. These 
provide some of the same functions as the graphics library routines, but the Intuition functions perform more 
of the detail work for you. See the chapter "Intuition Images, Line Drawing and Text" for more information on 
Intuition rendering functions. Also see, of course, the chapters on screens, windows .gadgets , menus and 
requesters for information on managing the display. 

Output character-based data via the console device. The console device is discussed in the next section. 



Console Device I/O 



A program receives its input stream either directly from Intuition or via another mechanism known as the console 
device. 

The console device may be used both as a source for input and as a mechanism for output. Often, it is convenient to 
use only the console device for input and output. In particular, character-based programs can open the console and 
use it for all I/O without worrying about windows, bitmaps, or message ports. 

The console device gives the program "cooked" input data, including key code conversions to ASCII and conversions 
of Intuition generated events, such as IDCMP_CLOSEWINDOW, to ANSI escape sequences. 
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The console device output provides features such as automatic line wrapping and scrolling. If an application just 
wants to output text, it may choose to use the console device, which provides formatted text with little fuss. 

If the application is not character-based, it may be better for the it to use an IDCMP for input and render graphics and 
text directly through Intuition and the graphics library primitives. 

If necessary, it is possible to open both the console device and an IDCMP for input. Such a program might need 
ASCII input, formatted output and the IDCMP verification functions (for example, to verify that it has finished writing to 
the window before the user can bring up a requester). 

For more information on the console device, see the "Console Device" chapter of the Amiga ROM Kernel Reference 
Manual: Devices. 



Using the IDCMP 



The IDCMP allow the application to receive information directly from Intuition. The program can use the IDCMP to 
learn about mouse, keyboard and other Intuition events. Also, certain useful Intuition features, most notably the 
verification functions (described under "IDCMP Flags" below), require that the IDCMP be opened, as this is the only 
mechanism available for accessing these features. 

The IDCMP consists of a pair of message ports, which may be allocated and initialized by Intuition at the request of 
the program. Alternately, the application may choose to manage part of the allocation, such that one port is supplied 
by the application and one port is supplied by Intuition. These ports are standard Exec message ports, used to allow 
interprocess communications in the Amiga multitasking environment. To learn more about message ports and 
message passing, see the "Exec Messages and Ports" chapter. 



The IDCMP is always associated with a window, it is not possible to have an IDCMP without an open window. The 
IDCMP is made up of several fields in the Window structure: 

IDCMPFIags stores the IDCMP flags currently set for this port. This field should never be directly set by the 
application; use the function ModifylDCMPQ or set them when the window is opened instead. 

UserPort is a pointer to the standard Exec message port where the application receives input event 
messages from Intuition 

WindowPort is a pointer to the reply message port used by Intuition. The messages sent by Intuition are set 
up such that ReplyMsg() will return them to this port. 

To open these ports automatically, set at least one of the IDCMP flags in the OpenWindowTagList() call. To free 
these ports later in the program, call the function ModifylDCMP() with NULL for the IDCMP flags or simply close the 
window. 

Don't Reply Any Messages After the IDCMP is Freed. If an IDCMP is freed, either by 
calling ModifylDCMP() or by closing the window, Intuition will reclaim and deallocate all 
messages waiting at that port without waiting for a ReplyMsg(). If the program attempts 
to ReplyMsg() to an IntuiMessages after the IDCMP is closed, the system will probably 
crash. 
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If the IDCMP flags are NULL when the window is opened, no ports will be allocated when the window is created. To 
have Intuition allocate these ports later, call the function ModifylDCMPQ with any of the IDCMP flags set. (Starting in 
V37, ModifylDCMPQ returns NULL if it was unable to create the necessary message ports. Do not check the return 
code under V36 or earlier.) 

Once the IDCMP is opened, with the ports allocated, the program can receive many types of information directly from 
Intuition, based on the IDCMP flags that are set. 

The IDCMP allows the application to receive only the events that it considers important. The program can, for 
instance, choose to learn about gadget events but may not want to learn about other mouse or keyboard events. 
This is done by providing a "filter" or "mask" value for the IDCMP which tells Intuition which events it should send to 
this specific port. Only messages with a type matching one of the flags set in the Window structure's IDCMPFIags 
field will be sent to this port. These values may be set at creation time, or modified by calling the function 
ModifylDCMPQ. 

Messages sent to the IDCMP are instances of the structure IntuiMessage. This is an extended form of the Exec 
Message structure which allows Intuition to send user interface specific information to the application. The 
IntuiMessage structure is discussed at length below. 

After the application opens an IDCMP, it must monitor the port for messages. At a minimum, this involves removing 
all messages from the port and replying to them. An event loop which processes messages arriving at the IDCMP is 
discussed below. 

Standard IntuiMessage Event Loop 

The application should handle events quickly. Any delay in this handling will make the user interface appear sluggish 
to the user. Additionally, certain events such as IDCMP_SIZEVERIFY may time-out if the application does not 
respond to them quickly (this is to help prevent system deadlocks). The action taken by Intuition when an event 
times-out may not match the action desired by the program. When IDCMP_SIZEVERIFY times out, the window 
sizing operation is cancelled by Intuition. 

Code should be able to handle the case where there are multiple events waiting at the port. When events are being 
generated quickly, Intuition may post many events to the IDCMP before the application regains control. This can 
happen regardless of how fast the application processes the messages waiting at the port. Since messages queue 
up but signals do not, the application may not see a signal for each message posted. Because of these facts, the 



code should remove all the messages waiting at the port, regardless of the number, each time Wait() returns. 

Code should also be able to handle the case where the signal is set but no events are waiting at the port. This could 
happen if a new message arrives at the IDCMP while an application is still processing the previous message. Since 
applications typically process all queued messages before returning to Wait(), the second message gets handled with 
the signal bit still set. The subsequent call to Wait() will return immediately even though no message is present. 
These cases should be quietly ignored. 
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Event Loop Example 

This example shows how to receive Intuition events. It reports on a variety of events: close window, keyboard, disk 
insertion, select button up and down and menu button up and down. Note that the menu button events will only be 
recieved by the program if the WA_RMBTrap attribute is set for the window. 

;/* eventloop.c - Execute me to compile me with SAS C 5.10 

LC -bl -cfistq -v -y -J73 eventloop.c 

Blink FROM LIB : c . o, eventloop . o TO eventloop LIBRARY LIB : LC . lib, LIB : Amiga . lib 

quit 

* * 

** This example shows how to receive Intuition events. It reports on a 
** variety of events: close window, keyboard, disk insertion and removal, 
** select button up and down and menu button up and down. Note that the 
** menu button events will only be received by the program if the 
** WA_RMBTrap attribute is set for the window. 

* * 

** eventloop.c - standard technique to handle IntuiMessages from an IDCMP. 

*/ 

#define INTUI_V3 6_NAMES_ONLY 

#include <exec/types . h> 
#include <intuition/intuition.h> 

#include <clib/exec_protos . h> 
#include <clib/intuition_protos . h> 

#include <stdio.h> 

#ifdef LATTICE 

int CXBRK(void) { return ( ) ; } /* Disable Lattice CTRL/C handling */ 

int chkabort (void) { return(O); } /* really */ 

#endif 

/* our function prototypes */ 

BOOL handleIDCMP( struct Window *win, BOOL done); 

struct Library *IntuitionBase = NULL; 

/* 

** main routine. 

** Open required library and window, then process the events from the 

** window. Free all resources when done. 

*/ 

VOID main (int argc, char **argv) 

{ 

ULONG signals; 

UBYTE done; 

struct Window *win; 

IntuitionBase = (struct IntuitionBase *) OpenLibrary ( "intuition. library" , 37) ; 
if (IntuitionBase != NULL) 

{ 

if (win = OpenWindowTags (NULL, 

WA_Title, "Press Keys and Mouse in this Window", 



} 



WA_Width, 500, 

WA_Height, 50, 

WA_Activate, TRUE, 

WA_CloseGadget, TRUE, 

WA_RMBTrap , TRUE , 

WA_IDCMP, IDCMP_CLOSEWINDOW | IDCMP_VANILLAKEY | 
IDCMP_RAWKEY | IDCMP_DISKINSERTED | 
IDCMP_DISKREMOVED | IDCMP_MOUSEBUTTONS , 

TAG END) ) 



{ 

done = FALSE; 

/* perform this loop until the message handling routine signals 
** that we are done. 

* * 

** When the WaitO returns, check which signal hit and process 

** the correct port. There is only one port here, so the test 

** could be eliminated. If multiple ports were being watched, 

** the test would become: 

* * 

** signals = Wait ( (1L << winl->UserPort->mp_SigBit) | 

** (1L << win2->UserPort->mp_SigBit) | 

** (1L << win3->UserPort->mp_SigBit) ) 

** if (signals & (1L << winl->UserPort->mp_SigBit) ) 

** done = handleWinllDCMP (winl,done) ; 

** else if (signals & (1L << win2->UserPort->mp_SigBit) ) 

** done = handleWin2IDCMP (win2,done) ; 

** else if (signals & (1L << win3->UserPort->mp_SigBit) ) 

** done = handleWin3IDCMP (win3,done) ; 

* * 

** Note that these could all call the same routine with different 
** window pointers (if the handling was identical) . 

* * 

** handlelDCMP ( ) should remove all of the messages from the port. 

*/ 

while ( ! done) 

{ 

signals = Wait(lL << win->UserPort->mp_SigBit) ; 
if (signals & (1L << win->UserPort->mp_SigBit) ) 
done = handlelDCMP (win, done) ; 

}; 

CloseWindow(win) ; 

} 
CloseLibrary (IntuitionBase) ; 



} 



/* 

** handlelDCMP () - handle all of the messages from an IDCMP. 

*/ 

BOOL handlelDCMP (struct Window *win, BOOL done) 

{ 

struct IntuiMessage 'message; 

USHORT code; 

SHORT mousex, mousey; 

ULONG class; 

/* Remove all of the messages from the port by calling GetMsg ( ) 
** until it returns NULL. 

* * 

** The code should be able to handle three cases: 

* * 

** 1. No messages waiting at the port, and the first call to GetMsg ( ) 
** returns NULL. In this case the code should do nothing. 

* * 

** 2. A single message waiting. The code should remove the message, 
** processes it, and finish. 



* * 

* * 



* * 

** 3. Multiple messages waiting. The code should process each waiting 

** message, and finish. 

*/ 

while (NULL != (message = (struct IntuiMessage *) GetMsg (win->UserPort) ) ) 

{ 

/* It is often convenient to copy the data out of the message. 
In many cases, this lets the application reply to the message 
quickly. Copying the data is not required, if the code does 

** not reply to the message until the end of the loop, then 

** it may directly reference the message information anywhere 

** before the reply. 

*/ 

class = message- >Class ; 
code = message- >Code; 
mousex = message->MouseX; 
mousey = message->MouseY; 

/* The loop should reply as soon as possible. Note that the code 
** may not reference data in the message after replying to the 
** message. Thus, the application should not reply to the message 
** until it is done referencing information in it. 
* * 

** Be sure to reply to every message received with GetMsg ( ) . 

*/ 

ReplyMsg ( (struct Message *)message); 

/* The class contains the IDCMP type of the message. */ 
switch (class) 

{ 

case IDCMP_CLOSEWINDOW: 

done = TRUE ; 

break; 
case IDCMP_VANILLAKEY: 

printf ("IDCMP_VANILLAKEY (%lc) \n" , code) ; 

break; 
case IDCMP_RAWKEY: 

printf ( "IDCMP_RAWKEY\n" ) ; 

break ; 
case IDCMP_DISKINSERTED: 

printf ("IDCMP_DISKINSERTED\n") ; 

break ; 
case IDCMP_DISKREMOVED: 

printf ("IDCMP_DISKREMOVED\n") ; 

break ; 
case IDCMPJMOUSEBUTTONS : 

/* the code often contains useful data, such as the ASCII 

** value (for IDCMP_VANILLAKEY) , or the type of button 

** event here. 

*/ 

switch (code) 

{ 

case SELECTUP: 

printf ( "SELECTUP at %d, %d\n" , mousex, mousey) ; 

break ; 
case SELECTDOWN: 

printf ( "SELECTDOWN at %d, %d\n" , mousex, mousey) ; 

break; 
case MENUUP: 

printf ( "MENUUP\n" ) ; 

break ; 
case MENUDOWN: 

printf ( "MENUDOWN\n" ) ; 

break; 
default : 

printf ("UNKNOWN CODE\n") ; 

break; 



} 

break; 
default : 

print f ( "Unknown IDCMP message\n" ) ; 
break; 
} 
} 
return (done) ; 

} 

Setting Up A Custom User Port 

An application can use its own message port for the IDCMP instead of the one set up by Intuition, although some 
care is required. 

As described earlier, IDCMP communication takes place through a pair of Exec message ports attached to a window: 
the UserPort and the WindowPort. The UserPort is the port where the application receives IDCMP messages from 
Intuition. The WindowPort is the reply port where Intuition receives replies from the application (via the ReplyMsg() 
function). 

In the simplest case, Intuition allocates (and deallocates) both of these ports when the program opens a window with 
non-NULL IDCMP flags. Intuition will also allocate these ports if the application calls ModifylDCMP() with non-NULL 
flags for a window that has NULL IDCMP flags. These port variables will be set to NULL if there is no message port 
allocated, otherwise they will contain a pointer to a message port. 
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If the WindowPort is not already opened when either OpenWindowQ or ModifylDCMP() is called, it will be allocated 
and initialized. 

The UserPort is checked separately to see whether it is already opened. 

When Intuition initializes the UserPort, it also allocates a signal bit with a call to AllocSignal(). Since the application 
makes the call to OpenWindowTagList() or ModifylDCMPQ, this signal bit is valid for the application's task. The 
address of the application's task is saved in the SigTask variable of the message port. 

The program may choose to supply its own UserPort. This might be done in an environment where the program is 
using several windows and would prefer to monitor the input using only one message port. This is done by with the 
following procedure: 

1 . Create a port for the IDCMP by calling either the Exec function CreateMsgPortQ or the amiga.lib function 
CreatePort(), both of which return a pointer to a port. (CreateMsgPort() is a new Exec function in V36 and 
can therefore only be used on systems running Release 2 or a later version of the OS.) 

2. Open the windows with no IDCMP flags set. This will prevent Intuition from allocating a port for this window. 

3. Place a pointer to the port created in step 1 into the UserPort field of the Window structure. 

4. Call ModifylDCMPQ to set the desired IDCMP flags for the port. Intuition will use the port supplied with the 
window. 

Be Careful with Shared IDCMP Ports. If the application is sharing an IDCMP among 
several windows, it must be very careful not to call ModifylDCMP(window,NULL) for 
any of the windows that are using the shared port, as this will free the port and the signal 
bit. 

5. When an application decides to close a window that has a shared IDCMP, there may be messages waiting 
at the port for any of the windows including the window being closed. It is essential that messages destined 
for a given window be removed and replied to before that window is closed. 



CloseWindowSafely(), listed in the next example, performs proper message cleanup before closing such a 
window. It also sets the window's UserPort to NULL so that Intuition knows not to delete the port, which 
should be done by the application in this case. It is incorrect (and dangerous) to simply call CloseWindow() 
on a window that has a shared IDCMP. 

Note that CloseWindowSafely() assumes that the window has a UserPort. 

6. After all windows have been closed, and the port has been removed from each, delete the port that was 

created in step 1 . Use the amiga.lib function DeletePortQ (if CreatePort() was used) or the Exec function 
DeleteMsgPort() (if CreateMsgPort() was used). 
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Closing a Window with a Shared IDCMP 

As promised in the last section, this example shows the CloseWindowSafelyQ function. Use this function to close 
ay window that share an IDCMP port with another window. 

/* This example shows the CloseWindowSaf ely ( ) function. Use this 

** function to close any windows that share an IDCMP port with another 

** window. 

* * 

** CloseWindowSaf ely . c 

** these functions close an Intuition window that shares a port with other 
** Intuition windows. 

* * 

** We are careful to set the UserPort to NULL before closing, and to free 
** any messages that it might have been sent. 

*/ 

#include "exec/types .h" 

#include "exec/nodes . h" 

#include "exec/lists .h" 

#include "exec/ports .h" 

#include " intuit ion/ intuit ion. h" 

/* 

** function to remove and reply all IntuiMessages on a port that have been 
** sent to a particular window (note that we don't rely on the ln_Succ 
** pointer of a message after we have replied it) 

*/ 

VOID StripIntuiMessages (struct MsgPort *mp, struct Window *win) 

{ 

struct IntuiMessage *msg; 

struct Node *succ; 

msg = (struct IntuiMessage *) mp->mp_MsgList . lh_Head; 

while (succ = msg->ExecMessage .mn_Node . ln_Succ) 

{ 

if (msg->IDCMPWindow == win) 

{ 

/* Intuition is about to free this message. 

** Make sure that we have politely sent it back. 

*/ 

Remove (msg) ; 

ReplyMsg (msg) ; 

} 
msg = (struct IntuiMessage *)succ; 

} 



/* 



* * 



Entry point to CloseWindowSaf ely ( } 



** Strip all IntuiMessages from an IDCMP which are waiting for a specific 

** window. When the messages are gone, set the UserPort of the window to 

** NULL and call Modif yIDCMP (win, 0) . This will free the Intuition arts of 

** the IDMCMP and trun off message to this port without changing the 

** original UserPort (which may be in use by other windows) . 

*/ 

VOID CloseWindowSaf ely ( struct Window *win) 

{ 

/* we forbid here to keep out of race conditions with Intuition */ 
Forbid () ; 

/* send back any messages for this window that have not yet been 
** processed 

*/ 

StripIntuiMessages (win->UserPort , win) ; 

/* clear UserPort so Intuition will not free it */ 
win->UserPort = NULL; 

/* tell Intuition to stop sending more messages */ 
ModifylDCMP (win, 0L) ; 

/* turn multitasking back on */ 
Permit ( ) ; 

/* Now it's safe to really close the window */ 

CloseWindow(win) ; 

} 
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IntuiMessages 

The IntuiMessage structure is an Exec Message that has been extended to include Intuition specific information. 
The ExecMessage field in the IntuiMessage is an actual instance of a Message structure and is used by Exec to 
manage the transmission of the message. The Intuition extensions of the IntuiMessage are used to transmit 
specialized Intuition data to the program. 

struct IntuiMessage 

{ 

struct Message ExecMessage; 

ULONG Class; 

UWORD Code; 

UWORD Qualifier; 

APTR IAddress; 

WORD MouseX, MouseY; 

ULONG Seconds, Micros; 

struct Window *IDCMPWindow; 

struct IntuiMessage *SpecialLink; 

} ; 

The IntuiMessage structure fields are as follows: 

ExecMessage 

This field is maintained by Exec. It is used for linking the message into the system and broadcasting it to a 
message port. See the chapter "Exec Messages and Ports" for more information on the Message 
structure and its use. 



Class 



Class contains the IDCMP type of this specific message. By comparing the Class field to the IDCMP 
flags, the application can determine the type of this message. Each message may only have a single 
IDCMP type. 



Qualifier 



Code 

Code contains data set by Intuition, such as menu numbers or special code values. The meaning of the 
Code field changes depending on the IDCMP type, or Class, of the message. Often the code field will 
simply contain a copy of the code of the input event which generated this IntuiMessage. 

For example, when the message is of class IDCMPRAWKEY, Code contains the raw key code generated 
by the keyboard device. When the message is of class IDCMP_VANILLAKEY, Code contains the key 
mapped ASCII character. 

This contains a copy of the ie_Qualifier field that is transmitted to Intuition by the input device. This field is 
useful if your program handles raw key codes, since the Qualifier tells the program, for instance, whether 
or not the Shift key or Ctrl key is currently pressed. Check the <devices/inputevent.h> file for the 
definitions of the qualifier bits. 

MouseX and MouseY 

Every IntuiMessage will have the mouse coordinates in these variables. The coordinates can either be 
expressed as absolute offsets from the upper left corner of the window, or expressed as the amount of 
change since the last reported positions (delta). If IDCMP_DELTAMOVE is set, then these numbers will 
represent delta positions from the last position. All messages will have zero in these values except 
IDCMP_MOUSEMOVE and IDCMP_MOUSEBUTTON events, which will have the correct delta values for 
the movement. If IDCMP_DELTAMOVE is not set, then these numbers are the actual window offset 
values. 
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Seconds and Micros 

These values are copies of the current system clock, in seconds and microseconds. They are set when 
Intuition generates the message. 

Microseconds (Micros) range from zero up to one million minus one. The 32 bits allocated to the Seconds 
variable has enough accuracy to count up to 1 39 years. Time is measured from Jan 1 , 1 978. 

lAddress 

Typically this variable contains the address of some Intuition object, such as a gadget. The type of the 
object depends on the Class of the IntuiMessage. Do not assume that the object is of a certain type 
before checking the Class of the object. 

The lAddress pointer is defined only for the following IDCMP Classes. Do not attempt to dereference or 
otherwise interpret the lAddress field of any other type of IntuiMessage. 

IntuiMessage Class Meaning of lAddress Field 

IDCMP_GADGETDOWN lAddress points to the gadget. 

IDCMP_GADGETUP lAddress points to the gadget. 

IDCMPRAWKEY lAddress points to the dead-key information. 

IDCMPJDCMPUPDATE lAddress points to a tag item list. 

Other classes No meaning. 

In particular, for IDCMP_MOUSEMOVE IntuiMessages emanating from GACT_FOLLOWMOUSE 
gadgets, the lAddress field does not point to the gadget. Interpreting the lAddress as a gadget pointer 
and trying to access the gadget's fields before ascertaining that the event is an IDCMP_GADGETUP or 
IDCMP_GADGETDOWN event is incorrect, and can lead to subtle or serious problems. 

(Note that GadTools gadgets do arrange for the lAddress to point to the gadget when 
IDCMP_MOUSEMOVE messages appear). 

IDCMPWindow 

Contains the address of the window to which this message was sent. If the application is sharing the 
window's UserPort between multiple windows, IDCMPWindow allows it to determine which of the windows 



the message was sent to. 

SpecialLInk 

For system use only. 

IDCMP Flags 

The application specifies the information it wants Intuition to send to it via the IDCMP by setting IDCMP flags. These 
may be set either when opening the window or by calling ModifylDCMPQ. 

The flags set may be viewed as a filter, in that Intuition will only post IntuiMessages to an IDCMP if the matching flag 
is set. Thus, the application will only receive the IDCMP messages whose Class matches one of the bits set in the 
window's IDCMP. 
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For many of these messages, there is a separation of the act of filtering these messages and causing Intuition to 
send the messages in the first place. For instance, menu help events may be activated for a window by setting the 
WA_MenuHelp attribute when the window is opened. However, the IDCMP will only receive the messages if the 
IDCMP_MENUHELP flag is set. If this flag is not set, then the events are passed downstream in the input and may be 
picked up by the console device. 

Mouse Event Message Classes and Flags 

IDCMP_MOUSEBUTTONS 

Contains reports about mouse button up and down events. The events will be sent to the application only if 
they are not used internally by Intuition. 

The Code field contains information on the specific mouse button event this message represents. The 
Code field will be equal to SELECTDOWN, SELECTUP, MENUDOWN, MENUUP, MIDDLEDOWN or 
MIDDLEUP, depending on the button pressed or released. In general, the select button is the left mouse 
button, the menu button is the right mouse button and the middle button is an optional third button usually 
located between the select and menu buttons. 

Often, a mouse button event has extra meaning to Intuition, and the application may hear about it through 
a more specific message, for example a gadget or menu event. Other times, no event is generated at all, 
such as when the user depth-arranges a screen by clicking on the screen depth gadget. Note that menu 
button events are normally consumed by Intuition for menu handling. If an application wishes to hear 
IDCMP_MOUSEBUTTONS events for the menu button, it must set the WA_RMBTrap attribute for its 
window. See the "Intuition Windows" chapter for more information. 

IDCMP_MOUSEMOVE 

Reports about mouse movements, sent in the form of x and y coordinates relative to the upper left corner of 
the window. One message will be sent to the application for each "tick" of the mouse. 

The application can opt to receive IDCMP_MOUSEMOVE events only while certain gadgets are active, or 
during normal window operation. These events are sent whenever a gadget with GACT_FOLLOWMOUSE 
gadget is active, or for any window that has the WA_ReportMouse attribute set. This window attribute can 
be set or cleared by the application at will. See the "Intuition Windows" chapter for full details. 

Requesting IDCMP_MOUSEMOVE messages can create a very large volume of messages arriving at the 
window's IDCMP. Do not request these messages unless the program is prepared to keep up with them. 
Starting in V36, Intuition limits the number of mouse move events that pile up at your IDCMP. 

All IDCMP messages contain a mouse x and y position that can be absolute values or delta values. See 
IDCMP_DELTAMOVE, below. If the application requires a less frequent reporting of the mouse position, 
consider using IDCMPJNTUITICKS. While IDCMP_MOUSEMOVE events are generated by changes in 
the mouse's position, IDCMPJNTUITICKS IntuiMessages are based on a timer. Since they contain 



mouse coordinates, they effectively sample the mouse position. These message come often enough for 
many applications, but not so frequently as to swamp the application. 

The program will not be sent IDCMP_MOUSEMOVE messages while Intuition has the layers of the screen 
locked (during menu operations and window sizing/dragging). This avoids problems of messages 
accumulating while the program is blocked, waiting to render into a locked layer. 
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IDCMP_DELTAMOVE 

IDCMP_DELTAMOVE is not a message type, and events will never be sent to the application with this 
IDCMP identifier. This flag is a modifier, which changes how mouse movements are reported. When this 
flag is set, mouse movements are sent as delta values rather than as absolute positions. 

The deltas are the amount of change of the mouse position from the last reported position. If the mouse 
does not move, then the delta values will be zero. 

This flag works in conjunction with the IDCMP_MOUSEMOVE flag. When IDCMP_DELTAMOVE is set, 
IDCMP_MOUSEBUTTONS messages will also have relative values, instead of the absolute window 
position of the mouse. 

Delta mouse movements are reported even after the Intuition pointer has reached the limits of the display. 
That is, if the pointer has reached the edge of the display and the user continues to move the mouse in the 
same direction, the IDCMP_MOUSEMOVE messages will continue to report changes in the mouse 
position even though the pointer is no longer moving. 

Gadget Event Message Classes and Flags 

IDCMP_GADGETDOWN 

IDCMP_GADGETDOWN messages are sent when the user selects a gadget that was created with the 
GACTJMMEDIATE flag set. The IntuiMessage structure's lAddress field will contain a pointer to the 
selected gadget. 

IDCMP_GADGETUP 

IDCMP_GADGETUP messages are sent when the user selects a gadget that was created with the 
GACT_RELVERIFY flag set. The IntuiMessage structure's lAddress field will contain a pointer to the 
selected gadget. 

IDCMP_CLOSEWINDOW 

IDCMP_CLOSEWINDOW messages are sent when the user selects the window's close gadget. Intuition 
does not close the window when the close gadget is selected. Rather, an IDCMP_CLOSEWINDOW 
message is sent to the window's IDCMP. It is up to the application to clean up and close the window itself. 
If closing a window means losing some data (perhaps the spreadsheet the user was working on), it would 
be appropriate for the application to first confirm that the user really meant to close the window. 

Menu Event Message Classes and Flags 

IDCMP_MENUPICK 

This flag indicates that the user has pressed the menu button. If a menu item was selected, the menu 
number of the menu item can be found in the Code field of the IntuiMessage. If no item was selected, the 
Code field will be equal to MENUNULL. 

IDCMP_MENUVERIFY 

This is a special verification mode which allows the program to confirm that it is prepared to handle Intuition 
rendering, in this case, allowing menus to be drawn in the screen. 
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This is a special kind of verification, in that any window in the entire screen that has this flag set must 
respond before the menu operations may proceed. Also, the active window of the screen is allowed to 



cancel the menu operation. This is unique to IDCMP_MENUVERIFY. Refer to the "Intuition Menus" for a 
complete description. 

Also see the "Verification Functions" section below for more information. 

IDCMP_MENUHELP 

This message is sent by Intuition when the user selects the Help key while the menu system is activated. If 
a menu item was selected, the menu number of the menu item can be found in the Code field of the 
IntuiMessage. If no item was selected, the Code field will be equal to MENUNULL. 

These messages will only be sent if the WA_MenuHelp attribute is set for the window. 

The menu number returned in IDCMP_MENUHELP may specify a position that cannot be generated 
through normal menu activity. For instance, the menu number may indicate one of the menu headers with 
no item or sub-item. See the chapter on "Intuition Menus" for more information. 

Requester Event Message Classes and Flags 

IDCMP_REQSET 

Intuition sends an 1DCMP_REQSET message to the window each time a requester opens in that window. 

IDCMP_REQCLEAR 

Intuition sends an IDCMP_REQCLEAR message to the window each time a requester is cleared from that 
window. 

IDCMP_REQVERIFY 

Set this flag to allow the application to ensure it is prepared for Intuition to render a requester in the 
window. With this flag set, Intuition sends the application a message that a requester is pending, and then 
waits for the application to reply before drawing the requester in the window. 

If several requesters open in the window, Intuition asks the application to verify only the first one. After 
that, Intuition assumes that all output is being held off until all the requesters are gone. 

By setting the IDCMP_REQSET and IDCMP_REQCLEAR flags, the application can track how many 
requesters are open in the window and when the last requester is cleared. Once all of the requesters are 
cleared from the window, it is safe to write to the window until another IDCMP_REQVERIFY is received. 

See the "Verification Functions" section below for more discussion on using this flag. 

Window Event Message Classes and Flags 

IDCMP_NEWSIZE 

Intuition sends this message after the user has resized the window. After receiving this, the program can examine the 
size variables in the window structure to discover the new size of the window. The message is sent, even if the size 
of the window did not actually change. 
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IDCMP_REFRESHWINDOW 

This message is sent whenever the window needs refreshing. This flag makes sense only with windows 
that have a refresh type of WA_SimpleRefresh or WA_SmartRefresh. 

As a minimum, the application must call BeginRefresh() and EndRefresh() for the window after receiving 
an IDCMP_REFRESHWINDOW event. Create the window with the WA_NoCareRefresh attribute if you do 
not want to manage these events. See the "Intuition Windows" chapter for details. 

Most of the graphics library calls used for display output are compatible with Intuition, with the exception of 
ScrollRaster(). Intuition will not send an IDCMP_REFRESHWINDOW event when damage is caused to a 
window by ScrollRasterQ. This may happen in a simple refresh window which is partially obscured by 
another window-the region that scrolls out from behind the front window will be damaged, but the window 



will receive no notification. 

Check the LAYERREFRESH bit in the Layer structure Flags field to see if damage did happen as a result 

of ScrollRaster(). 

IDCMP_SIZEVERIFY 

Set this flag if the program must complete some operation before the user sizes the window. When the 
user sizes the window, Intuition sends an IDCMP_SIZEVERIFY message to the application and then waits 
until the program replies before allowing the user to size the window. See the "Verification Functions" 
section below for some things to consider when using this flag. 

IDCMP_ACTIVEWINDOW and IDCMPJNACTIVEWINDOW 

Set these flags to discover when the window becomes activated or deactivated. 

Other Event Message Classes and Flags 

IDCMP_VANILLAKEY 

IDCMP_VANILLAKEY messages return keyboard events translated into the current default character 
keymap. The mapped character value is returned in the Code field of the IntuiMessage structure. 

An IDCMP_VANILLAKEY message is sent only if the translation results in a single byte value, therefore the 
program cannot read the Help or function keys using IDCMP_VANILLAKEY. 

Starting with V36, programs using IDCMP_VANILLAKEY which also require the additional information of 
special keys, such as the Help key and the function keys, may set both IDCMP_VANILLAKEY and 
IDCMP_RAWKEY. When this combination is used, all keypresses that map to single character values will 
be returned as IDCMP_VANILLAKEY events; all other keyboard events will be sent as IDCMP_RAWKEY 
messages. Note that IDCMP_VANILLAKEY processing uses all of the key-up events, so the application 
will only receive key-down events in the IDCMP_RAWKEY format. 

IDCMP_RAWKEY 

IDCMP_RAWKEY messages give the raw keycodes from the keyboard. The numeric value of the keycode 
is sent in the Code field. Separate codes are returned for key down and key up. Qualifier codes, such as 
Shift or Alt and whether this key is a repeat, may be found in the Qualifier field of the message. 

In general, the application should not assume any correspondence between the keycode and the key 
value. Character positions on the keyboard change from country to country, and the application should 
respect the keymap set by the user. 
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Programs using IDCMP_RAWKEY messages should perform their own key mapping by calling the 
console. device function RawKeyConvert(), or the keymap. library function MapRawKey(). (The latter is a 
bit more convenient, but is only available under V36 and higher). The Autodoc for the MapRawKey() 
function shows how you can process so-called dead keys. A dead key is a key combination that has no 
immediate effect, but instead modifies a subsequent keystroke. For example, on the default keymap, Alt-F 
is a dead key for the acute accent mark. The sequence of Alt-F followed by the E key yields an e with an 
acute accent. 

For an example of key mapping using the RawKeyConvert() call, see the rawkey.c example in the 
"Intuition Mouse and Keyboard" chapter. 

The application can assume that certain keys will always return the same raw keycode, these keys do not 
have to be mapped. In general these keys are in the high part of the keymap, above hex 40, and includes 
all non-alphanumeric keys. The fixed keys include the function keys, backspace, delete, help and cursor 
keys. 

IDCMP_NEWPREFS 

IDCMP_NEWPREFS messages are sent when the system Preferences are changed by a call to 
SetPrefsQ. The program can learn of these changes by setting this flag. 



After receiving a message of class IDCMP_NEWPREFS, the application should call GetPrefs() to obtain a 
copy of the new Preferences. 

Under the new Preferences scheme used in Release 2 and later versions of the OS, an 
IDCMP_NEWPREFS message will not always be sent when the user changes a Preferences setting. Only 
Preferences values available under V34, i.e., those that can be modified by a call to SetPrefs(), will cause 
an IDCMP_NEWPREFS message to be sent. New Preferences items such as overscan or font settings 
rely on filesystem notification for monitoring changes. See the chapter on"Preferences" for more 
information. 

This message type is broadcast to all IDCMP that have this flag set, not just to the active window. If the 
application has this flag set, it should be prepared to handle the event even if it is not active. 

IDCMP_DISKINSERTED and IDCMPJDISKREMOVED 

When the user inserts or removes a floppy disk from any drive, Intuition will send one of these message 
types. 

This message type is broadcast to all IDCMP that have this flag set, not just to the active window. If the 
application has this flag set, it should be prepared to handle the event even if it is not active. 

IDCMPJNTUITICKS 

Intuition sends these messages to the active window based on an internal timer which "ticks" roughly ten 
times a second. This provides the application with simple timer events from Intuition. 

Intuition does not allow IDCMPJNTUITICKS events to accumulate at a port. After an IDCMPJNTUITICKS 
message has been sent to a port, Intuition will not send another until the application replies to the first. 
This means that an application that has not been able to service the IDCMP for an extended period can 
expect at most one IDCMPJNTUITICKS message to be waiting at the port. 
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These events are to be used as "prods", and not as time counters. Do not rely on the timing accuracy of 
the event, or on the exact frequency at which they appear. Remember, IDCMPJNTUITICKS will only be 
sent to the active window. If the user selects another window, the events will no longer be received at the 
first window. 

IDCMPJDCMPUPDATE 

Used for notification from Boopsi custom gadgets. See the chapter on "BOOPSI" for more information. 
The lAddress field contains a pointer to a tag item list. Tag lists are described in the chapter "Utility 
Library". 

IDCMP_CHANGEWINDOW 

This message provides the window with notification of any change in the size or position of a window. 

There are two other message classes reserved for system use: 

IDCMPJ/VBENCHMESSAGE 

Special messages for Workbench, system use only. 

IDCMPJ.ONELYMESSAGE 

For internal tracking by Intuition, system use only. 

Verification Functions 

IDCMPJ3IZEVERIFY, IDCMP_REQVERIFY and IDCMPJVIENUVERIFY are exceptional in that Intuition sends an 
IntuiMessage to the application and then waits for the application to reply before Intuition proceeds. The application 
replies by calling the Exec function ReplyMsg(). 

The implication is that the user requested some operation but the operation will not happen immediately and, in fact, 



will not happen at all until the application says it is safe. Because this delay can be frustrating and intimidating, the 
program should strive to make the delay as short as possible. An application should always reply to a verification 
message as soon as possible. 

These problems may be overcome by setting up a separate task to monitor the IDCMP and respond to incoming 
IntuiMessages immediately. This is recommended where there is heavy traffic through the IDCMP, which occurs 
when many IDCMP flags are set. Monitoring with a separate task may not be appropriate if the main program must 
synchronize with the event before it can respond to the message. 

In previous versions of the operating system, it was not safe to leave any of the VERIFY functions enabled at a time 
when the task is unable to respond for a long period. This restriction included calls to AmigaDOS directly (with 
OpenQ, for example), or indirectly (with OpenLibrary(), for a disk based library, for example), when a VERIFY 
function was active. This was because there are many cases where AmigaDOS will put up a requester prompting the 
user for input, and Intuition may end up waiting for the application to reply to the VERIFY message, while the 
application waits for the AmigaDOS call to finish. Prior to Release 2, this deadlock would freeze the Amiga. 

Beginning with V36, Intuition will no longer wait forever for the application to respond to the verify messages. These 
messages will now time-out; that is, if the application does not respond within a set period, Intuition will act as if it had. 
Even in this case, though, the machine will appear to be locked up until the time-out occurs. 
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The application should use ModifylDCMP() to turn off all VERIFY messages before calling AmigaDOS, or functions 
that may call AmigaDOS. 

If the application sets up a separate task to monitor the IDCMP, and the task monitoring the IDCMP does not call 
AmigaDOS functions, and if the monitor task will always be able to reply to the VERIFY message without any help 
from the other task, then the above warning does not apply. 

For additional information, see the IDCMP_MENUVERIFY discussion in the "Intuition Menus" chapter, the 
IDCMP_REQVERIFY discussion in the "Intuition Requesters and Alerts" chapter and the IDCMP_SIZEVERIFY 
discussion in the "Intuition Windows" chapter. 

This message type is broadcast to all IDCMP on the screen that have this flag set, not just to the active window. If 
the application has this flag set, it should be prepared to handle the event even if it is not active. 



Function Reference 



The following are brief descriptions of the Intuition functions that relate to the use of input and output under Intuition. 
See the Amiga ROM Kernel Reference Manual: Includes and Autodocs for details on each function call. 

Table 9-1 : Functions for Intuition Input and Output 



Function Description 



ModifylDCMP() Change the message filter for an IDCMP. 

Starting in V37, this function has a return value. 
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Chapter 10 

Intuition Mouse and Keyboard 

In the Intuition system, the mouse is the normal method of making selections and the keyboard is used for 
entering character data. This section describes how users employ the mouse to interact with the system and how 
to arrange for a program to use the mouse. It also describes the use of the keyboard, both as a character input 
device and as an alternate method of controlling the mouse pointer. 

The Mouse 



The Amiga mouse is a small, hand-held input device connected to the Amiga by a flexible cable. The user can 
input horizontal and vertical coordinates with the mouse by sliding it around on a smooth surface. This movement 
causes the repositioning of a pointer on the display; whenever the mouse is moved the pointer moves, and in the 
same direction. 

The mouse also provides two or three input keys, called mouse buttons, that allow the user to input information to 
the computer. The basic activities the user can perform with the mouse are shown below. 



Action 


Explanation 


Moving the Mouse 


Sliding the body of the mouse over a 




surface, such as a desk top. 


Pressing a button 


Pushing down a mouse button (which is 




released at some later time). 


Clicking a button 


Quickly pressing and releasing a mouse 




button. 


Double clicking a button 


Clicking a button twice in a short 




period of time. 


Dragging 


Pressing a button and moving the mouse 




while the button is held down. The 




drag operation is completed by 




releasing the button. 



Table 10-1: Mouse Activities 
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The action associated with mouse button presses can occur when the button is first pressed, or while the button is 
held down, or when the button is released. As an example of this, consider the drag gadget of a window. When 
the select button of the mouse is first pressed an outline representing the window frame is drawn. While the 
button is held down the outline remains, and it moves with the pointer as the mouse is moved. When the button is 
released, the outline is erased and the window takes its new position. 

Intuition's Use of Mouse Events 

When the mouse is moved or its buttons are pressed, the system generates input events that represent the 
actions. The input events are taken from the input chain by Intuition when the active window requires the events. 
Note that only input for a specific window will be affected by changes in that window's IDCMP flags. 

Most events generated by the user with the mouse are used by Intuition. 

As the user moves the mouse, Intuition changes the position of its pointer. The Intuition pointer moves around the 
entire video display, mimicking the user's movement of the mouse. The user points at an object by positioning the 
hot spot of the pointer over the object. The hot spot is the active part of the pointer image; the hot spot for 
Intuition's default pointer is the pixel at the tip of the arrow. 

After pointing to an object, the user can perform some action on that object by selecting it with one of the mouse 
buttons. These can include any of the actions specified above, such as dragging or double clicking. 



The left mouse button is generally used for selection, while the right mouse button is most often used for 
information transfer. The terms selection and information are intentionally left open to some interpretation, as it is 
impossible to imagine all the possible uses for the mouse buttons. 

The selection/information paradigm can be crafted to cover most interaction between the user and an application. 
When using the mouse, the application should emphasize this model. It will help the user to understand and 
remember the mouse control of the application. 

Applications that handle mouse button events directly, bypassing the menu and gadget systems, should use the 
same selection/information model used by Intuition. 

Select Button 

When the user presses the left, or select button, Intuition examines the state of the system and the position of the 
pointer. This information is used to decide whether or not the user is trying to select some object, operation, or 
option. For example, the user positions the pointer over a gadget and then presses the left button to select that 
gadget. Alternatively, the user can position the pointer over a window and press the select button to activate the 
window. The pointer is said to be over an object when the pointer's hot spot is positioned within the selection 
region of the object. 
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A number of other common techniques involving the select button are available. They include: 

Drag Select 

Multiple objects or an extended area may be selected by dragging the mouse over a range with the 
select button held down. For instance, in Release 2, multiple icons can be selected in a Workbench 
window by pressing the select button while the pointer is over the background of the window (not an 
icon or a system gadget) and then moving the mouse with the select button held down. A selection 
rectangle will be displayed and all icons within the rectangle will be selected. Similarly, the user may 
highlight blocks of text in a console window by pressing the select button over the first desired 
character and dragging the mouse to the last desired character while holding the button down. 

Multi-Select or Shift Select 

Another way to select multiple objects or an extended area is through the shift select technique. First, 
select the first member of the group of objects in the normal way. Additional objects can be added to 
the group by holding down the Shift key while the select button is pressed. This technique works with 
Workbench icons, where icons may be added one-at-a-time to the list of selected icons; and with text in 
a console window, where the selected text is extended to include the new position. Note that text need 
not operate this way, and the application may allow multiple discrete blocks to be selected at any given 
time. 

Cancel Drag Operation 

Both drag select and the dragging of individual objects may often be canceled by pressing the right 
mouse button before completing the drag operation (before releasing the select button). Examples of 
this include window dragging and sizing, and positioning of Workbench icons. 

Menu Button 

The right mouse button is used to initiate and control information gathering processes. Intuition uses this button 
most often for menu operations. 

For most active windows, pressing the menu button will display the window's menu bar at the top of the screen. 
Dragging the mouse with the menu button depressed allows the user to browse through the available menus. 
Releasing the right mouse button over a menu item will select that item, if it is a valid choice. Additionally, the 
user can select multiple items by repeatedly pressing the select button while the menu button is held down. 

Drag selection is also available in menu operations. When the menu system is activated, and the user has the 
menu button pressed, the select button may be pressed and the mouse dragged over all items to be selected. 
This only works if the select button is pressed after the menu button, and all items that the pointer travels over will 
be selected. 

Double clicking the right mouse button can bring up a special requester for extended exchange of information. 



This requester is called the double-menu requester, because a double click of the menu button is required to 
reveal it, and because this requester acts like a super menu through which a complex exchange of information 
can take place. Because the requester is used for the transfer of information, it is appropriate that this mechanism 
is called up by using the right button. 

The programmer should consult the Amiga User Interface Style Guide for more information on the standard uses 
of the mouse and its buttons. 
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Button activation and mouse movements can be combined to create compound instructions. For example, 
Intuition combines multiple mouse events when displaying the menu system. While the right button is pressed to 
reveal the menu items of the active window, the user can move the mouse to position the pointer and display 
different menu items and sub-items. Additionally, multiple presses of the left button can be used to select more 
than one option from the menus. 

Dragging can have different effects, depending on the object being dragged. Dragging a window by the drag 
gadget will change the position of the window. Dragging a window by the sizing gadget will change the size of the 
window. Dragging a range in a Workbench window will select all of the icons in the rectangular range. 

Mouse Messages 

Mouse events are broadcast to the application via the IDCMP or the console device. See the "Intuition Input and 
Output Methods" chapter in this book for information on the IDCMP. See the "Console Device" chapter in the 
Amiga ROM Kernel Reference Manual: Devices for more about the console device. 

Simple mouse button activity not associated with any Intuition function will be reported to the window as an 
IntuiMessage with a Class of IDCMP_MOUSEBUTTONS. The IntuiMessage Code field will be set to 
SELECTDOWN, SELECTUP, MIDDLEDOWN, MIDDLEUP, MENUDOWN or MENUUP to specify changes in the 
state of the left, middle and right buttons, respectively. 

Direct select button events will not be received by the program if the select button is pressed while the pointer is 
positioned over a gadget or other object which uses the button event. For example, select button activity over a 
gadget is reported with a Class of IDCMP_GADGETDOWN or IDCMP_GADGETUP. The gadget is said to have 
consumed 'the mouse events and produced gadget events. 

If the menu system is enabled, menu selections appear with a Class of IDCMP_MENUPICK. To directly receive 
menu button events, the application must set the flag WFLG_RMBTRAP for the window either when the window 
is opened or by changing the flag in a single, atomic operation. See the chapter "Intuition Windows" for more 
information on the flag WFLG_RMBTRAP. 

The program receives mouse position changes in the event Class IDCMP_MOUSEMOVE. The MouseX and 
MouseY position coordinates describe the position of the mouse relative to the upper left corner of the reference 
window. These coordinates are always in the resolution of the screen being used, and may represent any pixel 
position on the screen, even though the hardware sprites can be positioned only on the even numbered pixels of 
a high resolution screen and on the even numbered rows of an interlaced screen. Enabling 
IDCMP_MOUSEMOVE messages is discussed below in the section on "The Pointer". 

To get mouse movement reported as deltas (amount of change from the last position) instead of as absolute 
positions, set the IDCMP flag IDCMP_DELTAMOVE. When IDCMP_DELTAMOVE is set, the 
IDCMP_MOUSEMOVE messages received by the program will have delta values rather than absolute values. 
Note that IDCMP_DELTAMOVE is simply a flag used to modify the behavior of IDCMP_MOUSEMOVE, and that 
no messages of class IDCMP_DELTAMOVE are ever sent. 

Each window has a queue limit for the number of IDCMP_MOUSEMOVE messages waiting on its IDCMP at any 
given time. If the number of mouse move messages waiting at the IDCMP is equal to the queue limit, then 
Intuition will discard additional IDCMP_MOUSEMOVE messages until the application replies to one of the queued 
mouse move messages. The default queue limit for mouse move messages is five. 
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Be aware that this may cause some data loss, especially when the application is using IDCMP_DELTAMOVE, as 
the information contained in the discarded messages is not repeated. When using IDCMP_DELTAMOVE, this 
could cause the application to lose track of the actual pointer position. The application may wish to change the 



default mouse queue size if it is unable to reply to messages queued at the IDCMP for an extended period. The 
mouse queue can be set when the window is opened by using the WA_MouseQueue tag, and may later be 
modified using the SetMouseQueue() call. Note that the actual mouse position is always available to the 
application through the Window structure MouseX and MouseY. 

Mouse Usage Example 

The example program below shows the use of IDCMP_MOUSEBUTTONS, IDCMP_MOUSEMOVE and 
DoubleClick(). DoubleClick() is used to test the interval between two times and determine if the interval is within 
the user specified time for double clicking as set in the Preferences Input editor. 

BOOL Doubleclick ( unsigned long sSeconds, unsigned long sMicros, 

unsigned long cSeconds, unsigned long cMicros ); 

The sSeconds and sMicros arguments specify a timestamp value describing the start of the double click time 
interval to be tested. The cSeconds and cMicros arguments specify a timestamp value describing the end of the 
double click time interval to be tested. 

DoubleClick() returns TRUE if the time interval was short enough to qualify as a double-click. A FALSE return 
indicates that the time interval between presses took too long. The button presses should be treated as separate 
events in that case. 

;/* mousetest.c - Execute me to compile me with SAS C 5.10 

LC -bl -cfistq -v -y -j73 mousetest.c 

Blink FROM LIB: c . o,mousetest . o TO mousetest LIBRARY LIB: LC. lib, LIB: Amiga. lib 

quit 

** mousetest.c - Read position and button events from the mouse. 

*/ 

#define INTUI V3 6 NAMES ONLY 

#include <exec/types.h> 
#include <intuition/intuition.h> 
#include <graphics/gfxbase.h> 
#include <devices/inputevent .h> 

#include <clib/exec protos. h> 
#include <clib/graphics protos . h> 
#include <clib/intuition protos . h> 

#include <stdio.h> 

#ifdef LATTICE 

int CXBRK(void) { return(O); } /* Disable Lattice CTRL/C handling */ 

int chkabort (void) { return(O); } /* really */ 

#endif 

#define BUFSIZE 16 

/* something to use to track the time between messages 

** to test for double-clicks. 

*/ 

typedef struct myTimeVal 

{ 

ULONG LeftSeconds; 
ULONG LeftMicros; 
ULONG RightSeconds; 
ULONG RightMicros; 
} MYTIMEVAL; 

/* our function prototypes */ 

VOID doButtons (struct IntuiMessage *msg, MYTIMEVAL *tv) ; 

VOID process window (struct Window *win) ; 

struct Library *IntuitionBase; 

struct Gf xBase *Gf xBase; /* we need Gf xBase- >DefaultFont */ 



** main() -- set-up everything. 

*/ 

VOID main(int argc, char **argv) 

{ 

struct Window *win; 
struct Screen *scr; 
struct Drawlnfo *dr info; 
ULONG width; 

/* Open the libraries we will use. Requires Release 2 (KS V2.04, V37) */ 
if (IntuitionBase = OpenLibrary ("intuition. library" , 37) ) 

{ 

if (GfxBase = (struct GfxBase *) OpenLibrary ("graphics. library" , 37)) 

{ 

/* Lock the default public screen in order to read its Drawlnfo data */ 

if (scr = LockPubScreen (NULL) ) 

{ 

if (dr info = GetScreenDrawInfo (scr) ) 

{ 

/* use wider of space needed for output (18 chars and spaces) 

* or titlebar text plus room for titlebar gads (approx 18 each) 

*/ 
width = max( (GfxBase->DefaultFont->tf XSize * 18), 

(18 * 2) + TextLength(&scr->RastPort, "MouseTest", 9) ) ; 

if (win = OpenWindowTags (NULL, 

WA Top , 2 0, 

WA Left, 100, 

WA InnerWidth, width, 

WA Height, (2 * GfxBase->DefaultFont->tf YSize) + 

scr->WBorTop + scr->Font->ta YSize + 1 + 
scr->WBorBottom, 

WA Flags, WFLG DEPTHGADGET | WFLG CLOSEGADGET | 
WFLG ACTIVATE j WFLG REPORTMOUSE j 
WFLG RMBTRAP | WFLG DRAGBAR, 

WA IDCMP, IDCMP CLOSEWINDOW | IDCMP RAWKEY | 

IDCMP MOUSEMOVE | IDCMP MOUSEBUTTONS , 

WA_Title, "MouseTest" , 

WA PubScreen, scr, 

TAG END) ) 

{ 

printf ("Monitors the Mouse:\n"); 

printf(" Move Mouse, Click and Doubleclick in Window\n") ; 

SetAPen (win->RPort,dr info- >dri Pens [TEXTPEN] ) ; 
SetBPen (win ->RPort,dr_info->dri Pens [BACKGROUNDPEN] ) ; 
SetDrMd (win- >RPort , JAM2 ) ; 

process window (win) ; 

CloseWindow(win) ; 

} 
FreeScreenDrawInfo (scr, dr info) ; 

} 
UnlockPubScreen (NULL, scr) ; 

} 
CloseLibrary ( (struct Library *)GfxBase); 

} 
CloseLibrary (IntuitionBase) ; 

} 
} 

/* 

** process window () - simple message loop for processing IntuiMessages 

*/ 

VOID process window (struct Window *win) 

{ 

USHORT done; 

struct IntuiMessage *msg; 

MYTIMEVAL tv; 

UBYTE prt buff [14] ; 

LONG xText, yText; /* places to position text in window. */ 



done = FALSE; 

tv.Lef tSeconds = 0; /* initial values for testing double-click */ 

tv.Lef tMicros = 0; 

tv.RightSeconds = 0; 

tv.RightMicros = 0; 

xText = win->BorderLef t + (win->IFont->tf XSize * 2) ; 

yText = win->BorderTop + 3 + win->IFont->tf Baseline; 

while (!done) 

{ 

Wait ( (lL<<win->UserPort->mp SigBit) ) ; 

while ((!done) && 

(msg = (struct IntuiMessage *) GetMsg(win->UserPort) ) ) 

{ 

switch (msg->Class) 

{ 

case IDCMP CLOSEWINDOW: 

done = TRUE; 

break; 
/* NOTE NOTE NOTE: If the mouse queue backs up a lot. Intuition 
** will start dropping MOUSEMOVE messages off the end until the 
** queue is serviced. This may cause the program to lose some 
** of the MOUSEMOVE events at the end of the stream. 
** 

** Look in the window structure if you need the true position 
** of the mouse pointer at any given time. Look in the 
** MOUSEBUTTONS message if you need position when it clicked. 
** An alternate to this processing would be to set a flag that 
** a mousemove event arrived, then print the position of the 
** mouse outside of the "while (GetMsgO)" loop. This allows 
** a single processing call for many mouse events, which speeds 
** up processing A LOT! Something like: 
** 

** while (GetMsgO ) 

** / 

** if (class == IDCMP MOUSEMOVE) 

** mouse flag = TRUE; 

** ReplyMsgO; NOTE: copy out all needed fields first ! 

** \ 

** if (mouse flag) 
** / 

** process mouse event () ; 

** mouse flag = FALSE; 

** \ 

** 

** You can also use IDCMP INTUITICKS for slower paced messages 

** (all messages have mouse coordinates.) 

*/ 

case IDCMP MOUSEMOVE: 

/* Show the current position of the mouse relative to the 

** upper left hand corner of our window 

*/ 

Move (win- >RPort,xText, yText) ; 

sprintf(prt buff, "X%5dY%5d", msg->MouseX, msg->MouseY) ; 

Text (win->RPort,prt buff, 13) ; 

break; 
case IDCMP MOUSEBUTTONS : 

doButtons (msg,&tv) ; 

break; 

} 
ReplyMsg( (struct Message *)msg); 



} 

/* 

** Show what mouse buttons where pushed 

*/ 

VOID doButtons (struct IntuiMessage *msg, MYTIMEVAL *tv) 

{ 



/* Yes, qualifiers can apply to the mouse also. That is how 
** we get the shift select on the Workbench. This shows how 
** to see if a specific bit is set within the qualifier 
*/ 

if (msg->Qualifier &. (IEQUALIFIER LSHIFT | IEQUALIFIER RSHIFT) ) 
printf ("Shift ") ; 

switch (msg->Code) 

{ 

case SELECTDOWN: 

printf ("Left Button Down at X%ld Y%ld", msg->MouseX, msg->MouseY) ; 

if (DoubleClick(tv->Lef tSeconds, tv->Lef tMicros, msg->Seconds, msg->Micros) ) 
printf (" Doubleclick!"); 

else 

{ 

tv->Lef tSeconds = msg->Seconds; 
tv->Lef tMicros = msg->Micros; 
tv->RightSeconds = 0; 
tv->RightMicros = 0; 

} 

break; 
case SELECTUP: 

printf ("Left Button Up at X%ld Y%ld", msg->MouseX, msg->MouseY) ; 

break; 
case MENUDOWN: 

printf ("Right Button down at X%ld Y%ld", msg->MouseX, msg->MouseY) ; 

if (DoubleClick(tv->RightSeconds, tv->RightMicros, msg->Seconds, msg->Micros) ) 
printf (" Doubleclick!"); 

else 

{ 

tv->Lef tSeconds = 0; 

tv->Lef tMicros = 0; 

tv->RightSeconds = msg->Seconds; 

tv->RightMicros = msg->Micros; 

} 
break; 
case MENUUP: 

printf ("Right Button Up at X%ld Y%ld", msg->MouseX, msg->MouseY) ; 
break; 

} 
printf ("\n") ; 

} 



The Pointer 



The system provides a pointer to allow the user to make selections from menus, choose gadgets, and so on. The 
user may control the pointer with a mouse, the keyboard cursor keys or some other type of controller. The 
specific type of controller is not important, as long as the proper types of input events can be generated. 

The pointer is associated with the active window and the input focus. The active window controls the pointer 
imagery and receives the input stream from the mouse. The pointer and mouse may be used to change the input 
focus by selecting another window. 

Pointer Position 

There are two ways to determine the position of the pointer: by direct examination of variables in the window 
structure at any time, and by examining messages sent by Intuition which inform the application of pointer 
movement. The pointer coordinates are relative to the upper left corner of the window and are reported in the 
resolution of the screen, even though the pointer's visible resolution is always in low-resolution pixels (note that 
the pointer is actually a sprite). 
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The MouseX and MouseY fields of the Window structure always contain the current pointer x and y coordinates, 
whether or not the window is the active one. If the window is a GimmeZeroZero window, the variables 
GZZMouseX and GZZMouseY in the Window structure contain the position of the mouse relative to the upper 
left corner of the inner window. 



If the window is receiving mouse move messages, it will get a set of x,y coordinates each time the pointer moves. 
To receive messages about pointer movements, the WFLG_REPORTMOUSE flag must be set in the Window 
structure. This flag can be set when the window is opened. The flag can also be modified after the window is 
open by calling ReportMouse(), however C programmers should avoid this function. ReportMouseQ has 
problems due to historic confusion about the ordering of its C language arguments. Do not use ReportMouse() 
unless you are programming in assembler. C programmers should set the flag directly in the Window structure 
using an atomic operation. 

Most compilers generate atomic code for operations such as mywindow->f lags [ = wflg_reportmouse or 
mywindow->f lags &= ~wflg_reportmouse. If you are unsure of getting an atomic operation from your 
compiler, you may wish to do this operation in assembler, or bracket the code with a Forbid()/Permit() pair. 

After the WFLG_REPORTMOUSE flag is set, whenever the window is active it will be sent an 
IDCMP_MOUSEMOVE messages each time the pointer position changes. The window must have the IDCMP 
flag IDCMP_MOUSEMOVE set to receive these messages. 

Mouse movements can cause a very large number of messages to be sent to the IDCMP, the application should 
be prepared to handle them efficiently. 

Messages about pointer movements may also be activated by setting the flag GACT_FOLLOWMOUSE in an 
application Gadget structure. When this flag is set in a gadget, changes in the pointer position are reported as 
long as the gadget is selected by the user. These messages are also sent as IDCMP_MOUSEMOVE messages. 

Custom Pointer 

An application can set a custom pointer for a window to replace the default pointer. This custom pointer will be 
displayed whenever the window is the active one. 

To place a custom pointer in a window, call SetPointer(). 

void SetPointer ( struct Window *window, UWORD *pointer, long height, 
long width, long xOffset, long yOffset ) ; 

Set the window argument to the address of the window that is to receive this custom pointer definition. The 
pointer argument is the address of the data that defines the custom pointer image. The format of this data is 
discussed in the next section, "The Sprite Data Structure". 

The height and width specify the dimensions of the pointer sprite. There is no height restriction but the width of 
the sprite must be less than or equal to 16. 

The xOffset and yOffset are used to offset the top left corner of the hardware sprite imagery from what Intuition 
regards as the current position of the pointer. Another way of describing this is the offset of the default Intuition 
pointer hot spot from the top left corner of the sprite. 
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For instance, by specifying offsets of (0,0), the top left corner of the sprite image will be placed at the pointer 
position. On the other hand, specifying an xOffset of -7 (remember, sprites are 16 pixels wide) will center the 
sprite over the pointer position. Specifying an xOffset of -1 5 will place the right edge of the sprite will be over the 
pointer position. 

Specifying the Hot Spot. For compatibility, the application must specify that the "hot spot" of 
the pointer is one pixel to the left of the desired position. Changes to the pointer done by a 
program must compensate for this. The Preferences Pointer editor correctly handles this 
situation. 

To remove the custom pointer from the window, call ClearPointer(). 

void ClearPointer ( struct Window *window ) ; 

Set the window argument to the address of the window that is to have its custom pointer definition cleared. The 
pointer will be restored to the default Intuition pointer imagery 



SetPointerQ and ClearPointerQ take effect immediately if the window is active, otherwise, the change will only 
be displayed when the window is made active. 

The Sprite Data Structure 

To define the pointer, set up a sprite data structure (sprites are one of the general purpose Amiga graphics 
structures). The sprite image data must be located in Chip memory, which is memory that can be accessed by the 
special Amiga hardware chips. Expansion, or Fast memory cannot be addressed by the custom chips. Ensure 
that data is in Chip memory by using the AllocMem() function with the MEMF_CHIP flag, and copying the data to 
the allocated space. Alternately, use the tools or flags provided by each compiler for this purpose. See the "Exec 
Memory Allocation" chapter for more information. 

A sprite data structure is made up of words of data. In a pointer sprite, the first two words and the last two words 
are reserved for the system and should be set to zero. All other words contain the sprite image data. 

The pointer in the example, a standard busy pointer, is sixteen lines high and sixteen pixels wide. Currently, all 
sprites are two bit planes deep, with one word of data for each line of each plane. The example sprite image 
consists of 36 words (2 planes x 18 lines = 36 words). Add to this the four reserved words of control information 
for a total of 40 words of data. See the example below for the complete data definition. 

The sprite data words are combined to determine which color will appear at each pixel position of each row of the 
sprite. The first two words of image data, 0x0400 and 0x07C0, represent the top line of the sprite. The numbers 
must be viewed as binary numbers and combined in a bit-wise fashion. The highest bit from each word are 
combined to form a two bit number representing the color register for the leftmost pixel. The next two bits 
represent the next pixel in the row, and so on, until the low order bits from each word represent the rightmost pixel 
in the row. 
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For example: 

Hex Binary 



Second word 0x07CO 00000 1 1111 000000 
First word 0x0400 00000 1 0000 000000 

\ A A A / 



I ' -- 00 = color 

1 -- 10 = color 2 
1 -- 11 = color 3 
'-- 00 = color 

Pointer Color Ordering. The first word in a line gives the least significant bit of the color 
register and the second word gives the most significant bit. 

Sprites get their color information from the color registers much like screens do. See the Amiga Hardware 
Reference Manual for more information on the assignment of color registers to sprites. Note that the color 
number given above is added to a base number to determine the actual hardware color register. 

The colors of the Intuition pointer may be changed. The Intuition pointer is always sprite 0. To change the colors 
of sprite 0, call the graphics library routine SetRGB4(). 

Pointer Example 

The program below shows how to set the pointer for a window. In this example, the pointer imagery is changed to 
a stopwatch symbol which could be used to indicate a busy period. 



;/* custompointer .c - Execute me to compile me with SAS C 5.10 

LC -bl -cfistq -v -y -j73 custompointer . c 

Blink FROM LIB: c . o, custompointer . o TO custompointer LIBRARY LIB: LC. lib, LIB: Amiga. lib 

quit 

** 

** The program shows how to set the pointer for a window. In this 

** example, the pointer imagery is changed to a stopwatch symbol which 

** could be used to indicate a busy period. 

** 

** custompointer .c - Show the use of a custom busy pointer, as well as 

** using a requester to block input to a window. 

*/ 

#define INTUI V3 6 NAMES ONLY 

#include <exec/types.h> 
#include <exec/libraries.h> 
#include <intuition/intuition.h> 

#include <clib/exec protos.h> 
#include <clib/dos protos.h> 
#include <clib/intuition protos . h> 



#ifdef LATTICE 

int CXBRK(void) { return(O); } 

int chkabort (void) { return (0); } 

#endif 



/* Disable Lattice CTRL/C handling */ 
/* really */ 



struct Library *IntuitionBase; 

UWORD chip waitPointer [] = 

{ 

0x0000, 0x0000, /* reserved, must be NULL */ 



0x0400, 
0x0000, 
0x0100, 
0x0000, 
0x07C0, 
OxlFFO, 
0x3 FF8, 
0x3 FF8, 
0x7FFC, 
0x7EFC, 
0x7FFC, 
0x3 FF8, 
0x3 FF8, 
OxlFFO, 
0x07C0, 
0x0000, 



0x07C0, 
0x07C0, 
0x0380, 
0x07E0, 
0xlFF8, 
0x3 FEC, 
0x7 FDE, 
0x7 FBE, 
0xFF7F, 
OxFFFF, 
OxFFFF, 
0X7FFE, 
0X7FFE, 
0x3 FFC, 
0xlFF8, 
0x07E0, 



0x0000, 0x0000, 



/* reserved, must be NULL */ 



** The main() routine 

*/ 

VOID main (int argc, char **argv) 

{ 

struct Window *win; 

struct Requester null request; 

extern UWORD chip waitPointer [] ; 



if (IntuitionBase = OpenLibrary ("intuition. library" , 37) ) 

{ 

/* the window is opened as active (WA Activate) so that the busy 

** pointer will be visible. If the window was not active, the 

** user would have to activate it to see the change in the pointer. 

*/ 

if (win = OpenWindowTags (NULL, 

WA Activate, TRUE, 

TAG END) ) 



{ 

/* a NULL requester can be used to block input 

** in a window without any imagery provided. 

*/ 

InitRequester (fcnull request) ; 

Delay(50); /* simulate activity in the program. */ 

/* Put up the requester to block user input in the window, 

** and set the pointer to the busy pointer. 

*/ 

if (Request (&null request, win)) 

{ 

SetPointer (win, waitPointer, 16, 16, -6, 0); 

Delay(lOO); /* simulate activity in the program. */ 

/* clear the pointer (which resets the window to the default 

** pointer) and remove the requester. 

*/ 

ClearPointer (win) ; 

EndRequest (&null request, win); 

} 

Delay(lOO); /* simulate activity in the program. */ 

CloseWindow(win) ; 

} 
CloseLibrary (IntuitionBase) ; 

} 
} 
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The Keyboard 

A program can receive keyboard data through an IDCMP port by setting the IDCMP_RAWKEY flag, the 
IDCMPJVANILLAKEY flag or both. IDCMP_VANILLAKEY events provide for simple ASCII text and standard 
control keys like space, return and backspace. IDCMP_RAWKEY events provide a more complex input stream, 
which the program must process to generate ASCII data. IDCMP_RAWKEY returns all keycodes, both key-up 
and key-down, including function keys. 

Keystrokes Are Not Always Paired. Keystrokes do not always come in key-down/key-up pairs. 
For example, repeating keys appear as a sequence of key-down messages. 

IDCMP_RAWKEY and IDCMPJVANILLAKEY may be set together. When both flags are set in the IDCMP, 
IDCMPVANILLAKEY messages will be sent for keystrokes that directly map to a single ASCII value. 
IDCMP_RAWKEY messages will be sent for key sequences that do not map to simple values, i.e. if a key 
sequence does not map to an IDCMPJVANILLAKEY message, it will be sent as an IDCMP_RAWKEY message. 
This allows easy access to mapped characters through IDCMPJVANILLAKEY with control characters returned as 
IDCMP_RAWKEY. Note that the IDCMP_RAWKEY events will only return the key down events when used with 
IDCMPJVANILLAKEY. 

When Intuition responds to an input event or sequence of events, the application will not receive those events. 
This happens for system shortcuts (left Amiga + key) if the system shortcut is defined, and for menu shortcuts 
(right Amiga + key) if the menu shortcut is defined for the active window. If the shortcut is not defined, then the 
appropriate key event will be sent with the proper Amiga qualifier set. 

Key repeat characters have a queue limit which may be set for each window, much like the mouse queue 
described above. The key repeat queue limit may only be set when the window is opened using the 
WA_RptQueue tag, there is no function call for modifying the value after the window is open. The default queue 
limit for key repeat characters is three. This limit causes any IDCMP_RAWKEY, IDCMPJVANILLAKEY or 
IDCMP_UPDATE message with the IEQUALIFIER_REPEAT bit set to be discarded if the queue is full 
(IDCMP_UPDATE is discussed in the "BOOPSI" chapter). The queue is said to be full when the number of 
waiting repeat key messages is equal to the queue limit. Note that the limit is not per character, it is on the total 
number of key messages with the repeat bit set. Once the limit is reached, no other repeat characters will be 
posted to the IDCMP until the application replies to one of the outstanding repeat key messages. The repeat 



queue limit is not as dangerous as the mouse queue limit as only duplicate keystroke information is discarded, 
where the mouse queue limit discards information that cannot be easily reproduced. 

Rawkey Keymapping Example 

The following example uses RawKeyConvert() to convert IDCMP_RAWKEY input stream into an ANSI input 
stream. See the "Console Devices" changer in the Amiga ROM Kernel Reference Manual: Devices for more 
information on RawKeyConvert() and the data it returns. 

;/* rawkey. c - Execute me to compile me with SAS C 5.10 

LC -bl -cfistq -v -y -j73 rawkey. c 

Blink FROM LIB: c . o, rawkey . o TO rawkey LIBRARY LIB: LC. lib, LIB: Amiga. lib 

quit 

** 

** The following example uses RawKeyConvert ( ) to convert the 

** IDCMP RAWKEY input stream into an ANSI input stream. See the 

** "Console Device" chapter in the Amiga ROM Kernel Reference Manual: 

** Devices for more information on RawKeyConvert ( ) and the data it 

** returns. 

** 

** rawkey. c - How to correctly convert from RAWKEY to keymapped ASCII 

*/ 

#define INTUI V3 6 NAMES ONLY 

#include <exec/types.h> 
#include <exec/memory.h> 
#include <intuition/intuition.h> 
#include <devices/inputevent .h> 
#include <clib/exec protos. h> 
#include <clib/intuition protos . h> 
#include <clib/console protos. h> 
#include <stdio.h> 

#ifdef LATTICE 

int CXBRK(void) { return(O); } /* Disable Lattice CTRL/C handling */ 

int chkabort (void) { return(O); } /* really */ 

#endif 

/* our function prototypes */ 

LONG deadKeyConvert (struct IntuiMessage *msg, UBYTE *kbuffer, 

LONG kbsize, struct KeyMap *kmap, struct InputEvent *ievent) ; 
VOID print qualifiers (ULONG qual) ; 
BOOL doKeys (struct IntuiMessage *msg, struct InputEvent *ievent, 

UBYTE **buf fer, ULONG *bufsize) ; 
VOID process window (struct Window *win, struct InputEvent *ievent, 

UBYTE **buf fer, ULONG *bufsize) ; 

/* A buffer is created for RawKeyConvert ( ) to put its output. BUFSIZE is the size of 
** the buffer in bytes. NOTE that this program starts out with a buffer size of 2. 
** This is only to show how the buffer is automatically increased in size by this 
** example! In an application, start with a much larger buffer and you will probably 
** never have to increase its size. 128 bytes or so should do the trick, but always 
** be able to change the size if required. 
*/ 
#define BUFSIZE (2) 

struct Library *IntuitionBase, *ConsoleDevice; 

/* main() - set-up everything used by program. */ 
VOID main (int argc, char **argv) 

{ 

struct Window *win; 
struct IOStdReq ioreq; 
struct InputEvent *ievent; 
UBYTE *buffer; 
ULONG bufsize = BUFSIZE; 

if (IntuitionBase = OpenLibrary ("intuition. library" , 37) ) { 

/* Open the console device just to do keymapping. (unit -1 means any unit) */ 
if (0 == OpenDevice ("console. device" , -1, (struct IORequest *)&ioreq,0)) { 
ConsoleDevice = (struct Library *) ioreq. io Device; 



{ 



WA Height , 
WA Flags, 
WA IDCMP , 
WA Title, 
TAG END) ) 



/* Allocate the initial character buffer used by deadKeyConvert ( ) and RawKeyConvert ( ) 

** for returning translated characters. If the characters generated by these routines 

** cannot fit into the buffer, the application must pass a larger buffer. This is 

** done in this code by freeing the old buffer and allocating a new one. 

*/ 

if (buffer = AllocMem(buf size, MEMF CLEAR) ) { 

if (ievent = AllocMem(sizeof (struct InputEvent) , MEMF CLEAR) \ 
if (win = OpenWindowTags (NULL, 
WAWidth, 300, 
50, 
WFLG DEPTHGADGET | WFLG CLOSEGADGET | WFLG ACTIVATE, 
IDCMP CLOSEWINDOW | IDCMP RAWKEY, 
"Raw Key Example", 

{ 
printf ("Press keyboard keys to see ASCII conversion from rawkey\n") 
printf ("Unprintable characters will be shown as %c\n\n" , 0x7f ) ; 
process window (win, ievent, &buf fer,&buf size) ; 
CloseWindow(win) ; 

} 
FreeMem( ievent, sizeof (struct InputEvent)) ; 

} 
/* Buffer can be freed elsewhere in the program so test first. */ 
if (buffer != NULL) 

FreeMem(buf fer,buf size) ; 

} 
CloseDevice ( (struct IORequest *)&ioreq); 

} 
CloseLibrary (IntuitionBase) ; 

} 



Convert RAWKEYs into VANILLAKEYs, also shows special keys like HELP, Cursor Keys, 
FKeys, etc. It returns: 

-2 if not a RAWKEY event. 

-1 if not enough room in the buffer, try again with a bigger buffer. 

otherwise, returns the number of characters placed in the buffer. 



/* 

** 
** 
** 
** 

*/ 

LONG deadKeyConvert (struct IntuiMessage *msg, UBYTE *kbuffer, 

LONG kbsize, struct KeyMap *kmap, struct InputEvent *ievent) 

{ 

if (msg->Class != IDCMP RAWKEY) return(-2); 

ievent->ie Class = I ECLASS RAWKEY; 

ievent ->ie Code = msg->Code; 

ievent->ie Qualifier = msg->Qualif ier; 

ievent->ie position. ieaddr = * ( (APTR*)msg->IAddress) ; 

return (RawKeyConvert (ievent, kbuffer, kbsize, kmap) ) ; 



} 



/* print qualifiers () - print out the values found in the qualifier bits of 

** the message. This will print out all of the qualifier bits set. 

*/ 

VOID print qualifiers (ULONG qual) 

{ 

printf ("Qual: ") ; 



if 


qual 


& 


IEQUALIFIER LSHIFT) 


printf 


"LShft,") ; 


if 


qual 


& 


IEQUALIFIER RSHIFT) 


printf 


"RShft, ") ; 


if 


qual 


& 


IEQUALIFIER CAPSLOCK) 


printf 


"CapLok, ") ; 


if 


qual 


& 


IEQUALIFIER CONTROL) 


printf 


"Ctrl, ") ; 


if 


qual 


& 


IEQUALIFIER LALT) 


printf 


"LAlt, ") ; 


if 


qual 


& 


IEQUALIFIER RALT) 


printf 


"RAlt, ") ; 


if 


qual 


& 


IEQUALIFIER LCOMMAND) 


printf 


"LCmd, ") ; 


if 


qual 


& 


IEQUALIFIER RCOMMAND) 


printf 


"RCmd, ") ; 


if 


qual 


& 


IEQUALIFIER NUMERICPAD) 


printf 


"NumPad, ") ; 


if 


qual 


& 


IEQUALIFIER REPEAT) 


printf 


"Rpt, ") ; 


if 


qual 


& 


IEQUALIFIER INTERRUPT) 


printf 


"Intrpt, ") ; 


if 


qual 


& 


IEQUALIFIER MULTIBROADCAST) 


printf 


"Multi Broadcast 


if 


qual 


& 


IEQUALIFIER MIDBUTTON) 


printf 


"MidBtn, ") ; 


if 


qual 


& 


IEQUALIFIER RBUTTON) 


printf 


"RBtn, ") ; 


if 


qual 


& 


IEQUALIFIER LEFTBUTTON) 


printf 


"LBtn, ") ; 


if 


qual 


& 


IEQUALIFIER RELATIVEMOUSE) 


printf 


"RelMouse, ") ; 



} 

/* doKeysO - Show what keys were pressed. */ 

BOOL doKeys (struct IntuiMessage *msg, struct InputEvent *ievent, 
UBYTE **buffer, ULONG *bufsize) 

{ 

USHORT char pos; 

USHORT numchars; 

BOOL ret code = TRUE; 

UBYTE realc, c; 

/* deadKeyConvert ( ) returns -1 if there was not enough space in the buffer to 

** convert the string. Here, the routine increases the size of the buffer on the 

** fly... Set the return code to FALSE on failure. 

*/ 

numchars = deadKeyConvert (msg, *buffer, *bufsize - 1, NULL, ievent) ; 

while ((numchars == -1) &.&. (*buffer != NULL)) { 

/* conversion failed, buffer too small, try to double the size of the buffer. */ 

FreeMem(*buf fer, *bufsize) ; 

*bufsize = *bufsize << 1; 

printf ("Increasing buffer size to %d\n", *bufsize) ; 

if (NULL == (*buffer = AllocMem(*buf size, MEMF CLEAR) ) ) ret code = FALSE; 
else numchars = deadKeyConvert (msg, *buffer, *bufsize - 1, NULL, ievent); 
} 

/* numchars contains the number of characters placed within the buffer. Key up events and */ 
/* key sequences that do not generate any data for the program (like deadkeys) will return */ 
/* zero. Special keys (like HELP, the cursor keys, FKeys, etc.) return multiple characters */ 
/* that have to then be parsed by the application. Allocation failed above if buffer isNULL*/ 
if (*buffer != NULL) { 

/* if high bit set, then this is a key up otherwise this is a key down */ 

if (msg->Code & 0x8 0) 

printf ("Key Up: ") ; 

else 

printf ("Key Down: ") ; 

print qualifiers (msg->Qualif ier) ; 

printf (" rawkey #%d maps to %d ASCII character (s) \n" , 0x7F & msg->Code, numchars); 

for (char pos = 0; char pos < numchars; char pos++) { 

realc = c = ("buffer) [char pos] ; 

if ( (c <= OxlF) | | ( (c >= 0x80) &&(c < OxaO) ) ) 
c = 0x7 f; 

printf (" %3d ($%02x) = %c\n", realc, realc, c) ; 

} 
} 
return (ret code) ; 

} 

/* process window () - simple event loop. Note that the message is not replied 
** to until the end of the loop so that it may be used in the doKeysO call. 
*/ 

VOID process window (struct Window "win, struct InputEvent "ievent, 
UBYTE ""buffer, ULONG "bufsize) 

{ 

struct IntuiMessage "msg; 
BOOL done; 

done = FALSE; 

while (done == FALSE) { 

Wait ( (lL<<win->UserPort->mp SigBit) ) ; 

while ((done == FALSE) &.&. (msg = (struct IntuiMessage *) GetMsg(win->UserPort) ) ) { 
switch (msg->Class) { /* handle our events */ 
case IDCMP CLOSEWINDOW: 
done = TRUE; 
break; 
case IDCMP RAWKEY: 

if (FALSE == doKeys (msg, ievent, buffer, bufsize) ) 

done = TRUE; 
break; 

} 
ReplyMsg( (struct Message *)msg); 



Keyboard Control of the Pointer 

All Intuition mouse activities can be emulated using the keyboard, by combining the Amiga command keys with 
other keystrokes. 

The pointer can be moved by holding down either Amiga key along with one of the four cursor keys. The mouse 
pointer accelerates the longer these keys are held down. Additionally, holding down either Shift key will make the 
pointer jump in larger increments. The pointer position may also be adjusted in very fine increments through this 
technique. By holding down either Amiga key and briefly pressing one of the cursor keys, the pointer may be 
moved one pixel in any direction. 

Press the left Alt key and either one of the Amiga keys simultaneously emulates the left button of the mouse. 
Similarly, pressing the right Alt key and either one of the Amiga keys simultaneously emulates the right button of 
the mouse. These key combinations permit users to make gadget selections and perform menu operations using 
the keyboard alone. 

Intuition Keyboard Shortcuts 

If Intuition sees a command key sequence that means nothing to it, the key sequence is sent to the active window 
as usual. See the chapter on "Intuition Input and Output Methods" for how this works. This section and the next 
section describe what Intuition does when it recognizes certain special command key sequences. 
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It is recommended that programs abide by certain command key standards to provide a consistent interface for 
Amiga users. The Amiga User Interface Style Guide contains a complete list of the recommended standards. 

There are a number of special keyboard shortcuts supported by Intuition. These involve holding down the left 
Amiga key and simultaneously pressing a another key. These functions allow the user to do such things as move 
the Workbench screen to the front using the keyboard. 

Table 10-2: Intuition Keyboard Shortcuts 



Keyboard Shortcut 


Function Performed 


left Amiga M 


Move frontmost screen to back. 


left Amiga N 


Move Workbench screen to front. 


left Amiga B 


System requester cancel, or select the 




rightmost button in the system requester. 


left Amiga V 


System requester OK, or select the leftmost 




button in the system requester. 


left Amiga + mouse 


Screen drag from any point. By holding down 


select button 


the left Amiga key, the user may drag the 




screen with the mouse from any part of the 




screen or window on the screen. 



About System Keyboard Shortcuts. Many of these keyboard commands may be remapped 
through the IControl Preferences editor. Do not rely on the values reported here. 

Intuition consumes these command key sequences for its own use. That is, it always detects 
these events and removes them from the input stream. The application will not see the events. 



Menu Shortcuts 



Menu items and sub-items may be paired with command key sequences to associate certain characters with 
specific menu item selections. This gives the user a shortcut method to select frequently used menu operations, 
such as Undo, Cut, and Paste. Whenever the user presses the right Amiga key with an alphanumeric key, the 
menu strip of the active window is scanned to see if there are any command key sequences in the list that match 
the sequence entered by the user. If there is a match, Intuition translates the key combination into the appropriate 
menu item number and transmits the menu number to the application program. 



Menu Shortcuts Look Like the Real Thing. To the application it looks as if the user had 
selected a given menu item with the mouse. The program will receive a menu event, not a key 
event. For more information on menu item selection, see the "Intuition Menus" chapter. 

Amiga Qualifiers 

The Amiga keyboard has several special qualifiers which are listed in the next table. Most of these qualifiers are 
associated with special keys on the keyboard such as the Shift or Ctrl key. These keys are used to modify the 
meaning of other keys. Other qualifiers are associated with mouse button status. For a complete list of all the 
qualifiers, see the include file <devices/inputevent.h>. 
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The Qualifier field of each IntuiMessage contains the status of all the qualifiers. An individual application should 
never attempt to track the state of any of the qualifier keys or mouse buttons even though key-down and key-up 
information may be available. Instead use the information available in the Qualifier field of the IntuiMessage 
structure. 

Table 10-3: Keyboard Qualifiers 



Qualifier 

Type 

Control 



Amiga 



Alternate 



Key Label 
-Ctrl 



Fancy A 



Alt 



Shift 



Up Arrow 



Caps Lock 

Numeric Pad 
Repeat 
Mouse Buttons 



Caps Lock 



Explanation 

The IEQUALIFIER_CONTROL bit indicates 

that the Control key is depressed. 

There are two Amiga keys, one on each 

side of the space bar. The left Amiga 

key is recognized by the Qualifier bit 

IEQUALIFIER_LCOMMAND, and the right 

Amiga key by IEQUALIFIER_RCOMMAND. 

There are two separate Alt keys, one on 

each side of the space bar, next to the 

Amiga keys. These can be treated 

separately, if desired. The left Alt 

key sets the IEQUALIFIER_LALT bit and 

the right Alt key sets the 

IEQUALIFIER_RALTbit. 

There are two separate Shift keys, one 

above each Alt key. These can be 

treated distinctly, if desired. The 

left Shift key sets the 

IEQUALIFIER_LSHIFT bit and the right 

Shift key sets the IEQUALIFIER_RSHIFT 

bit. 

The IEQUALIFIER_CAPSLOCK bit is set as 

long as the Caps Lock light is 

illuminated. 

The IEQUALIFIER_NUMERICPAD bit is set 

for keys on the numeric keypad. 

Repeat key events are sent with the 

IEQUALIFIER_REPEAT bit set. 

If mouse buttons are down when the 

event occurs, one or more of the three 

bits IEQUALIFIER_LEFTBUTTON, 

IEQUALIFIER_MIDBUTTON or 

IEQUALIFIER RBUTTON will be set. 



Function Reference 



The following are brief descriptions of the Intuition functions that relate to the use of the mouse and keyboard 
under Intuition. See the Amiga ROM Kernel Reference Manual: Includes and Autodocs for details on each 
function call. 



Table 10-4: Functions for Intuition Mouse and Keyboard 

hunction Description 



UoubleClick() I est two time values tor double click status. 

SelPuinler() Change Ihe Inluilion poinler imagery for an open 

window. 
ClearPointerQ Restore the default Intuition pointer imagery. 



SetMouseQueue() Change the mouse queue for an open window. 

ReportMouseQ A function C programmers should not use. 
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Intuition Special Functions 

There are several Intuition topics which, while not large enough to fill chapters of their own, nontheless deserve to 
be discussed. The subjects covered here include locking IntuitionBase, the Intuition memory functions 
AllocRemember() and FreeRemember(), using sprites with Intuition, and Intuition's special internal functions. 

Locking IntuitionBase 

It is sometimes necessary to examine the IntuitionBase structure. Items such as the address of the active 
screen and window, current mouse coordinates and more can be found there. It is never a good idea to simply 
read these fields, as they are prone to sudden change. The IntuitionBase structure must always be locked 
before looking at its fields. 

It is necessary to inform Intuition that an application is about to examine IntuitionBase so that Intuition will not 
change any variables and IntuitionBase will remain static during the access. The call LocklBase() will lock the 
state of IntuitionBase so that it may be examined. During the time that the application has IntuitionBase 
locked, all Intuition input processing is frozen. Make every effort to examine IntuitionBase and release the lock 
as quickly as possible. The values in IntuitionBase are read-only. Applications should never write values to 
IntuitionBase. 

ULONG LocklBase ( unsigned long dontknow ) ; 

LocklBaseQ is passed a ULONG (dontknow in the prototype above) indicating the Intuition lock desired. For all 
foreseeable uses of the call this value should be 0. LocklBaseQ returns a ULONG, that must be passed to 
UnlocklBase() later to allow IntuitionBase to change once again. 

Every call to LocklBaseQ must be matched by a subsequent call to UnlocklBase(): 

void UnlocklBase ( unsigned long ibLock ) ; 

Set the ibLock argument to the value returned by the previous call to LocklBase(). 
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About LocklBaseQ. This function should not be called while holding any other system locks 
such as Layer and Layerlnfo locks. Between calls to LocklBaseQ and UnlocklBaseQ, you 
may not call any Intuition or other high-level system functions so it is best to copy the 
information you need and release the lock as quickly as possible. 

About IntuitionBase. Never, ever, modify any of the fields in IntuitionBase directly. Also, 
there are fields in IntuitionBase that are considered system private that should not be 
accessed, even for reading. (Refer to the <intuition/intuitionbase.h> include file.) Application 
programs cannot depend on (and should not use) the contents of these fields; their usage is 
subject to change in future revisions of Intuition. 

Easy Memory Allocation and Deallocation 

Intuition has a pair of routines that enable applications to make multiple memory allocations which are easily 
deallocated with a single call. The Intuition routines for memory management are AllocRemember() and 
FreeRemember(). These routines rely upon the Remember structure to track allocations. 

Intuition Helps You Remember 

The AllocRemember() routine calls the Exec AllocMemQ function to perform the memory allocation. (Of course, 
the application may directly call Exec memory functions, see the chapter "Exec Memory Allocation" for details.) 



AllocRemember() performs two allocations each time it is called. Thefirst allocation is the actual memory 
requested by the application. This memory is of the size and type specified in the call and is independent of the 
second block of memory. The second allocation is memory for a Remember structure which is used to save the 
specifics of the allocation in a linked list. When FreeRemember() is called it uses the information in this linked list 
to free all previous memory allocations at once. This is convenient since normally you would have to free each 
memory block one at a time which requires knowing the size and base address of each one. 

The AllocRemember() call takes three arguments: 

APTR AllocRemember ( struct Remember **rememberKey, unsigned long size, 
unsigned long flags ) ; 

The rememberKey is the address of a pointer to a Remember structure. Note that this is a double indirection, 
not just a simple pointer. The size is the size, in bytes, of the requested allocation. The flags argument is the 
specification for the memory allocation. These are the same as the specifications for the Exec AllocMem() 
function described in the chapter on "Exec Memory Allocation". 

If AllocRemember() succeeds, it returns the address of the allocated memory block. It returns a NULL if the 
allocation fails. 

The FreeRemember() function gives the option of freeing memory in either of two ways. The first (and most 
useful) option is to free both the link nodes that AllocRemember() created and the memory blocks to which they 
correspond. The second option is to free only the link nodes, leaving the memory blocks for further use (and later 
deallocation via Exec's FreeMemQ function). But, as a general rule, the application should never free only the 
link nodes as this can greatly fragment memory. If the link nodes are not required, use the Exec memory 
allocation functions. 
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The FreeRemember() call is as follows: 

void FreeRemember ( struct Remember ** rememberKey, long reallyForget ) ; 

Set the rememberKey argument to the address of a pointer to a Remember structure. This is the same value 
that was passed to previous calls to AllocRemember(). The reallyForget argument is a boolean that should be 
set to TRUE. If TRUE, then both the link nodes and the memory blocks are freed. If FALSE, then only the link 
nodes are freed. Again, applications should avoid using the FALSE value since it can lead to highly fragmented 
memory. 

How to Remember 

To use Intuition's memory functions, first create an anchor for the memory to be allocated by declaring a variable 
that is a pointer to a Remember structure and initializing that pointer to NULL. This variable is called the 
remember key. 

struct Remember *rememberKey = NULL; 

Call AllocRemember() with the address of the remember key, along with the memory requirements for the 
specific allocation. Multiple allocations may be made before a call to FreeRemember(). 

memBlockA = AllocRemember (krememberKey, SIZE_A, 

MEMF_CLEAR | MEMF_PUBLIC) ; 
if (memBlockA == NULL) 

{ 

/* error: allocation failed */ 

printf ( "Memory allocation f ailed. \n" ) ; 

} 
else 

{ 

/* use the memory here */ 

printf ( "Memory allocation succeeded. \n" ) ; 

} 

AllocRememberQ actually performs two memory allocations per call, one for the memory requested and the 



other for a Remember structure. The Remember structure is filled in with data describing the allocation, and is 
linked into the list to which the remember key points. 

To free memory that has been allocated, simply call FreeRemember() with the correct remember key. 

void FreeRemember (krememberKey, TRUE); 

This will free all the memory blocks previously allocated with AllocRemember() in a single call. 

The Remember Structure 

The Remember structure is defined in <\ntuition/intuition.h> as follows: 

struct Remember 

{ 

struct Remember *NextRemember ; 

ULONG Remembers ize; 

UBYTE * Memory; 

}; 
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Generally, the Remember structure is handled only by the system. Here are its fields: 

NextRemember 

The link to the next Remember structure. 

RememberSize 

The size of the memory tracked by this node. 

Memory 

A pointer to the memory tracked by this node. 

An Example of Remembering 

;/* remembertest .c - Execute me to compile me with SAS C 5.10 

LC -bl -cfistq -v -y -j73 remembertest .c 

Blink FROM LIB: c . o, remembertest . o TO remembertest LIBRARY LIB: LC. lib, LIB: Amiga. lib 

quit 

** RememberTest - Illustrates the use of AllocRemember () and FreeRemember () . 

*/ 

#define INTUI V3 6 NAMES ONLY 

#include <exec/types.h> 
#include <exec/memory.h> 
#include <dos/dos.h> 
#include <intuition/intuition.h> 

#include <clib/exec protos.h> 
#include <clib/intuition protos . h> 

#include <stdlib.h> 

#ifdef LATTICE 

int CXBRK(void) { return(O); } /* Disable Lattice CTRL/C handling */ 

int chkabort (void) { return(O); } /* really */ 

#endif 

/* our function prototypes */ 
VOID methodOne (VOID) ; 
VOID methodTwo (VOID) ; 

struct IntuitionBase *IntuitionBase; 

/* random sizes to demonstrate the Remember functions. */ 
#define SIZE A 100L 



#define SIZE B 200L 

/* 

** main() - Initialize everything. 

*/ 

VOID main(int argc, char **argv) 

{ 

LONG exitVal = RETURN OK; 

IntuitionBase = OpenLibrary ("intuition. library" , 33L) ; 
if (IntuitionBase == NULL) 
exitVal = RETURN FAIL; 
else 

{ 

methodOne ( ) ; 

methodTwo ( ) ; 

CloseLibrary (IntuitionBase) ; 

} 
exit (exitVal) ; 

} 

/* 

** MethodOne 

** Illustrates using AllocRemember () to allocate all memory and 

** FreeRemember ( ) to free it all. 

*/ 

VOID methodOne (VOID) 

{ 

APTR memBlockA = NULL, memBlockB = NULL; 

struct Remember TememberKey = NULL; 

memBlockA = AllocRemember (fcrememberKey, SIZE A, MEMF CLEAR | MEMF PUBLIC) ; 
if (memBlockA) 

{ 

/* The memBlockA allocation succeeded; try for memBlockB. */ 

memBlockB = AllocRemember (fcrememberKey, SIZE B, MEMF CLEAR | MEMF PUBLIC) 

if (memBlockB) 

{ 

/* Both memory allocations succeeded. 

** The program may now use this memory. 

*/ 



/* It is not necessary to keep track of the status of each allocation. 

** Intuition has kept track of all successful allocations by updating its 

** linked list of Remember nodes. The following call to FreeRemember ( ) will 

** deallocate any and all of the memory that was successfully allocated. 

** The memory blocks as well as the link nodes will be deallocated because 

** the "ReallyForget" parameter is TRUE. 

** 

** It is possible to have reached the call to FreeRemember ( ) 

** in one of three states. Here they are, along with their results. 

** 

** 1. Both memory allocations failed. 

** RememberKey is still NULL. FreeRemember ( ) will do nothing. 

** 2. The memBlockA allocation succeeded but the memBlockB allocation failed. 

** FreeRemember ( ) will free the memory block pointed to by memBlockA. 

** 3. Both memory allocations were successful. 

** FreeRemember ( ) will free the memory blocks pointed to by 

** memBlockA and memBlockB. 

*/ 

FreeRemember (fcrememberKey, TRUE); 

} 

/* 

** MethodTwo 

** Illustrates using AllocRemember () to allocate all memory, 

** FreeRemember ( ) to free the link nodes, and FreeMemO to 

** free the actual memory blocks. 

*/ 



VOID methodTwo (VOID) 

{ 

APTR memBlockA = NULL, memBlockB = NULL; 
struct Remember TememberKey = NULL; 

memBlockA = AllocRemember (fcrememberKey, SIZE A, MEMF CLEAR | MEMF PUBLIC) ; 
if (memBlockA) 

{ 

/* The memBlockA allocation succeeded; try for memBlockB. */ 

memBlockB = AllocRemember (fcrememberKey, SIZE B, MEMF CLEAR | MEMF PUBLIC) ; 

if (memBlockB) 

{ 

/* Both memory allocations succeeded. 

** For the purpose of illustration, FreeRemember ( ) is called at 

** this point, but only to free the link nodes. The memory pointed 

** to by memBlockA and memBlockB is retained. 

*/ 

FreeRemember (fcrememberKey, FALSE); 

/* Individually free the two memory blocks. The Exec FreeMemO 

** call must be used, as the link nodes are no longer available. 

*/ 

FreeMem( (VOID *)memBlockA, SIZE A) ; 

FreeMem ( (VOID *)memBlockB, SIZE B) ; 

} 



/* It is possible to have reached the call to FreeRemember ( ) 

** in one of three states. Here they are, along with their results. 

** 

** 1. Both memory allocations failed. 

** RememberKey is still NULL. FreeRemember ( ) will do nothing. 

** 2. The memBlockA allocation succeeded but the memBlockB allocation failed. 

** FreeRemember ( ) will free the memory block pointed to by memBlockA. 

** 3. Both memory allocations were successful. 

** If this is the case, the program has already freed the link nodes 

** with FreeRemember ( ) and the memory blocks with FreeMemO . 

** When FreeRemember ( ) freed the link nodes, it reset RememberKey 

** to NULL. This (second) call to FreeRemember ( ) will do nothing. 

*/ 

FreeRemember (fcrememberKey, TRUE); 

} 



Current Time Values 



The function CurrentTime() gets the current time values. To use this function, first declare the variables 
Seconds and Micros. Then, when the application call the function, the current time is copied into the argument 
pointers. 

void CurrentTime ( ULONG *seconds, ULONG *micros ); 

See the DOS library Autodocs in the AmigaDOS Manual (Bantam Books) for more information on functions 
dealing with the date and time. The DOS library includes such functions as DateToStrQ, StrToDate(), 
SetFileDate() and CompareDates(). 

Using Sprites in Intuition Windows and 
Screens 

Sprite functionality has limitations under Intuition. The hardware and graphics library sprite systems manage 
sprites independently of the Intuition display. In particular: 

Sprites cannot be attached to any particular screen. Instead, they always appear in front of every 
screen. 

When a screen is moved, the sprites do not automatically move with it. The sprites move to their correct 



locations only when the appropriate function is called (either DrawGList() or MoveSprite()). 

Hardware sprites are of limited use under the Intuition paradigm. They travel out of windows and out of screens, 
unlike all other Intuition mechanisms (except the Intuition pointer, which is meant to be global). 

Remember that sprite data must be in Chip memory to be accessible to the custom chips. This may be done with 

a compiler specific feature, such as the chip keyword of SAS/C. Otherwise, Chip memory can be allocated with 

the Exec AllocMem() function or the Intuition AllocRemember() function, setting the memory requirement flag to 
MEMF_CHIP. The sprite data may then be copied to Chip memory using a function like CopyMem() in the Exec 
library. See the chapter "Graphics Sprites, Bobs and Animation" for more information. 
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Intuition and Preferences 

The SetPrefsQ function is used to configure Intuition's internal data states according to a given Preferences 
structure. This call relies on the Preferences system used in V34 and earlier versions of the OS. The old system 
has been largely superceded in Release 2. See the "Preferences" chapter for details. This routine is called only 
by: 

The Preferences program itself after the user changes Preferences settings (under V34 and earlier). 

AmigaDOS when the system is being booted up. AmigaDOS opens the devs:system-configuration file and 
passes the information found there to the SetPrefs() routine. This way, the user can create an environment and 
have that environment restored every time the system is booted. 

The function takes three arguments: 

struct Preferences *SetPrefs (struct Preferences *prefbuf, 

long size, long realThing) 

The prefbuf argument is a pointer to a Preferences structure that will be used for Intuition's internal settings. The 
size is the number of bytes contained in your Preferences structure. Typically, you will use sizeof(struct 
Preferences) for this argument. The realThing argument is a boolean TRUE or FALSE designating whether or 
not this is an intermediate or final version of the Preferences. The difference is that final changes to Intuition's 
internal Preferences settings cause a global broadcast of NEWPREFS events to every application that is listening 
for this event. Intermediate changes may be used, for instance, to update the screen colors while the user is 
playing with the color gadgets. 

About SetPrefsQ. The intended use for the SetPrefsQ call is entirely to serve the user. You 
should never use this routine to make your programming or design job easier at the cost of 
yanking the rug out from beneath the user. 

Refer to the chapter "Preferences" for information about the Preferences structure and the new Preferences 
procedure calls used in Release 2. 



Function Reference 



The following are brief descriptions of the Intuition functions discussed in this chapter. See the Amiga ROM 
Kernel Reference Manual: Includes and Autodocs for details on each function call. 

Table 11-1: Other Functions for Intuition 



Function Description 



AllocRemember() Allocate memory and track the allocation. 

FreeRemember() Free memory allocated with AllocRemember(). 



LocklBase() Lock IntuitionBase for reading. 

UnlocklBaseQ Unlock IntuitionBase when done reading. 



CurrentTime() Get the system time in seconds and micro-seconds. 

SetPrefs() An Intuition internal function you should try to 

avoid. 



Chapter 12 

Boopsi-Object Oriented 
Intuition 

Boopsi is an acronym for Basic Object Oriented Programming System for Intuition. Using the Object Oriented 
Programming (OOP) model, Boopsi represents certain Intuition entities, like Gadgets and Images, as objects. 

There are many advantages to using Boopsi: 

Boopsi makes Intuition customizable and extensible. Boopsi programmers can create new types of 
Boopsi objects to suit the needs of their applications. These new types of objects are part of Intuition 
and can be made public so other applications can use them. Because applications can share the new 
types, application writers don't have to waste their time duplicating each other's efforts writing the same 
objects. 

New types of Boopsi objects can build on old types of Boopsi objects, inheriting the old object's behavior. 
The result is that Boopsi programmers don't have to waste their time building new objects from scratch, 
they simply add to the existing object. 

OOP and Boopsi apply the concept of interchangeable parts to Intuition programming. A Boopsi 
programmer can combine different Boopsi objects (like gadgets and images) to create an entire 
Graphical User Interface (GUI). The Boopsi programmer doesn't have take the time to understand or 
implement the inner workings of these objects. The Boopsi programmer only needs to know how to 
interact with Boopsi objects and how to make them interact with each other. 

Boopsi objects have a consistent, command-driven interface. To the Boopsi programmer, there is no 
difference between displaying a text, border, or bitmap-based Boopsi image, even though they are 
rendered quite differently. Each image object accepts a single command to tell it to render itself. 

Before reading this chapter, you should already be familiar with several Amiga concepts. Boopsi is built on top of 
Intuition and uses many of its structures. These include Intuition gadgets, images, and windows. Boopsi also 
uses the tag concept to pass parameters. The "Utility Library" chapter of this manual discusses tags. The "Utility 
Library" chapter also discusses callback Hooks, which are important to the later sections of this chapter. 
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OOP Overview 

Understanding Boopsi requires an understanding of several of the concepts behind Object Oriented 
Programming. This section is a general overview of these concepts as they pertain to Boopsi. Because Boopsi is 
in part based on the concepts present in the OOP language Smalltalk, a reference book on Smalltalk may provide 
a deeper understanding of Boopsi in general. Timothy Budd's book entitled A Little Smalltalk (Addison-Wesley 
Publishing ISBN 0-201-10698-1) is a good start. 

In the Boopsi version of the Object Oriented Programming model, everything is an Object. For example, a 
proportional gadget named myprop is an object. Certain objects have similar characteristics and can be 
classified into groups called classes. As objects, Rover the dog, Bob the cat, and Sam the bird are all distinct 
objects but they all have something in common, they can all be classified as animals. As objects, myprop the 
proportional gadget, mystring the string gadget, and mybutton the button gadget all have something in common, 
they can all be classified as gadgets. A specific object is an instance of a particular class ("Rover" is an instance 
of class "animal", "myslidergadget" is an instance of class "gadget"). 

Notice that, although Rover, Bob, and Sam can all be classified as animals, each belongs to a subgroup of the 
animal class. "Rover" is an instance of class "dog", "Bob" is an instance of class "cat", and "Sam" is an instance 
of class "bird". Because each of these animal types share common characteristics, each type makes up its own 
class. Because dog, cat, and bird are subclassifications of the animal class, they are known as subclasses of the 



animal class. Conversely, the animal class is the superclass of the dog, cat, and bird classes. 

Following the branches upward from class to superclass will bring you to a universal root category from which all 
objects are derived. The OOP language Smalltalk calls this class "Object". 

Figure 12-1 : Object Diagram 
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Like Smalltalk, Boopsi also has a universal root catagory, rootclass. Currently, Intuition defines three immediate 
subclasses of rootclass. The first, gadgetclass, is the class of Boopsi gadgets. The second class, imageclass, 
makes up the class of Boopsi images. 

Unlike gadgetclass and imageclass, the remaining subclass, icclass, does not correspond to an existing Intuition 
entity, it is a concept new to Intuition. Icclass, or interconnection class, allows one Boopsi object to notify another 
Boopsi object when a specific event occurs. For example, consider a Boopsi proportional gadget and a Boopsi 
image object that displays an integer value. An application can connect these two objects so that the prop gadget 
tells the image object the prop gadget's current value, which the image object displays. Every time the user slides 
the prop gadget, the prop gadget notifies the image of the change and the image updates its display to reflect the 
prop gadget's current integer value. Because these objects are talking to each other rather than the application, 
the updates happen automatically. The application doesn't have to talk to the two objects, it only has to connect 
them. 
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Boopsi Image Object 




Figure 12-2: Simple Boopsi Diagram 

An object's characteristics and behavior are determined by its class. Each class can define a set of attributes and 
a set of methods that apply to all objects of that class. An attribute is a variable characteristic of an object. For 
example, an attribute for the animal class could be the number of legs an animal object has. An example of a 
Boopsi attribute is the X coordinate of a Boopsi image object. The data that makes up the values of an object's 



attributes is collectively known as the instance data for that object. 

The behavior of an object depends upon the set of methods associated to it by its class. A method is basically a 
function that applies to objects of that class. An example of a Boopsi method is the imageclass method 
IM_DRAW. This method tells a Boopsi image to draw itself. All Boopsi actions are carried out via methods. 

From the Object Diagram, two of the methods of the "animal" class could be "eat" and "sleep". One of the 
methods of the "dog" class could be "bark". Notice that instances of the "dog" class can do more than just bark, 
they can also eat and sleep. This is because a subclass inherits methods from its superclasses. If there were a 
subclass of dog called "attack dog", all instances of that class would be able to bark, eat, and sleep, as well as 
"attack". Due to inheritance, a subclass has all of the methods and all of the attributes of its superclass. For 
example, the lAHeight attribute is defined by imageclass. All instances of the subclasses of imageclass have 
their own lAJHeight attribute, even though the subclasses do not explicitly define lAJHeight. In turn, all instances 
of subclasses of the imageclass subclasses also inherit the lAJHeight attribute. All classes on levels below a 
class will inherit its methods and attributes. 

When an application or a Boopsi object wants another Boopsi object to perform a method, it passes it a command 
in the form of a Boopsi message. A Boopsi message tells an object which method to perform. The message may 
also contain some parameters that the method requires. 

Watch Out! The term "message" used in object oriented terminology can be little confusing to 
the Amiga programmer because the Boopsi message has nothing to do with an Exec 
message. 

Boopsi classes can be either public or private. Public classes have ASCII names associated with them and are 
accessible to all applications. Private classes have no ASCII name and normally can only be accessed by the 
application that created the private class. 
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Using Boopsi 

There are several levels on which a programmer can use Boopsi. The most elementary level is to use Intuition 
functions to create and manipulate Boopsi objects that are instances of existing, public classes. 

At present there is a hierarchy of 14 public classes built into Intuition: 

Figure 12-3: Class Diagram 
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Boopsi and Tags 

Boopsi uses tag lists to pass and manipulate its attributes. To Boopsi, each Tagltem (defined in 
<utility/tagitem.h>) in a tag list is an attribute/value pair. The Tagltem.ti_Tag field contains an ID for the attribute 
and the ti_Data field holds the attribute's value. 

For example, the string gadget class defines an attribute called STRINGA_LongVal, which is the current integer 



value of the gadget. Certain gadgetclass objects have an attribute called GAJmage. Its value is not an integer, it 
is a pointer to an image. 

Note that these tag lists can also contain utility. library Global System control tags (like TAG_SKIP and 
TAG_DONE), which Boopsi uses in processing its tag lists. Any application that ends up processing these lists 
should do so using the tag manipulation functions from utility. library. For more information on tags and 
utility.library, see the "Utility Library" chapter of this manual. 

Creating an Object 

The Intuition function NewObjectAQ creates a Boopsi object: 

mynewobject = APTR NewObjectA (Class *privclass, UBYTE *pubclass, 

struct Tagltem *myattrs) 

The pointer that NewObjectA() returns is a pointer to a Boopsi object. In general, Boopsi objects are "black 
boxes". This means the inner workings of Boopsi objects are not visible to the application programmer, so the 
programmer does not know what goes on inside it. This really means the inner workings of these objects are 
none of your business. Unless otherwise documented, only use an object pointer as a handle to the object. 
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To create an object, NewObjectA() needs to know what class the new object is an instance of. To create a public 
class object, pass a NULL pointer in privclass and an ASCII string in pubclass naming the object's public class. 
The privclass pointer is used to create a private class object, which is covered in the "Creating a Boopsi Class" 
section later in this chapter. 

The myattrs tag list is a list of tag/value pairs, each of which contains an initial value for some object attribute. 
Most objects have a set of attributes associated with them, so each attribute has a tag name. For Boopsi gadgets 
and images, the attributes include some of the values from the old Gadget and Image structures (position, size, 
etc.). 

Most applications use the stack-based version of NewObjectA(), NewObject(), to create objects. This allows an 
application to build the tag list of object attributes on the stack rather than having to allocate and initialize a tag 
list. A code sample from a program that creates a Boopsi string gadget might look like this: 

mystringgadget = (struct Gadget *) NewObject (NULL, "strgclass", 

GA_ID, 1L, 

GA_Left, OL, 

GA_Top, OL, 

STRINGA_LongVal , 100L, 
TAG_END) ; 

If NewObject() is successful, it returns a pointer to a new Boopsi gadget object. Otherwise, it returns NULL. The 
class "strgclass" is one of the public classes built into Release 2. It is a class of string gadgets. 

If you look at the diagram of the public classes built into Intuition, you'll see that strgclass is a subclass of 
gadgetclass. In the example above, the attribute tag IDs that start with "GA_" are defined by gadgetclass and not 
by strgclass. This is because strgclass inherits these attributes from its superclass, gadgetclass. The other 
attribute, STRINGA_LongVal, is defined by strgclass. It does two things. First, it tells the object that it is a special 
type of string gadget which only handles an integer value rather than a generic ASCII string. Second, it passes 
the object its initial integer value. 

Disposing of an Object 

When an application is done with an object it has to dispose of the object. To dispose of an object, use the 
Intuition function DisposeObject(): 

VOID DisposeObject (APTR boopsiobject); 

where boopsiobject is a pointer to the Boopsi object to be disposed. Note that some classes allow applications 
to connect child objects to a parent object so that when the application deletes the parent object, it automatically 
disposes of all of its children. Be careful not to dispose of an object that has already been disposed. 



Setting an Existing Object's Attributes 

An object's attributes are not necessarily static. An application can ask an object to set certain object attributes 
using the SetAttrs() function: 

ULONG SetAttrs (APTR myobject, Tagl, Valuel, . ..); 

Because Boopsi gadgets require some extra information about their display, they use a special version of this 
function, SetGadgetAttrsQ: 
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ULONG SetGadgetAttrs (struct Gadget *myobject, struct Window *w, 

struct Requester *r, Tagl, Valuel, . . . ) ; 

Here myobject is a pointer to the Boopsi object, w points to the gadget's window, r points to the gadget's 
requester, and the tag/value pairs are the attributes and their new values. The return value of SetAttrs() and 
SetGadgetAttrs() is class specific. In general, if the attribute change causes a visual change to some object, the 
SetAttrs()/SetGadgetAttrs() function should return a non-zero value, otherwise, these functions should return 
zero (see the Boopsi Class Reference in "Appendix B" of this manual for information on the return values for 
specific classes). The following is an example of how to set the current integer value and gadget ID of the gadget 
created in the NewObject() call above: 

SetGadgetAttrs (mystringgadget , mywindow, NULL, STRINGA_LongVal , 75L, 

GA_ID, 2L, 

TAG_END) ) ; 

This changes two of mystringgadget's attributes. It changes the gadget's current integer value to 75 and it 
changes the gadget's ID number to 2. 

Note that it is not OK to call SetGadgetAttrsQ on a Boopsi object thatisn't a gadget, nor is it OK to call SetAttrs() 
on a Boopsi gadget. 

Not all object attributes can be set with SetGadgetAttrs()/SetAttrs(). Some classes are set up so that 
applications cannot change certain attributes. For example, the imagery for the knob of a proportional gadget 
cannot be altered after the object has been created. Whether or not a specific attribute is "settable" is class 
dependent. For more information about the attributes of specific classes, see the Boopsi Class Reference in the 
Appendix B of this manual. 

Getting an Object's Attributes 

The Intuition function GetAttr() asks an object what the value of a specific attribute is: 

ULONG GetAttr (ULONG attrlD, APTR myobject, ULONG *mydata) ; 

where attrlD is the attribute's ID number, myobject is the object to get the attribute from, and mydata points to a 
data area that will hold the attribute value. This function returns a OL if the object doesn't recognize the attribute, 
otherwise it returns some non-zero value, the meaning of which depends on the class. In most cases, GetAttr() 
returns a 1 when it is successful. 

Not all object attributes are obtainable using the GetAttr() function. Some classes are set up so that applications 
cannot query the state of certain attributes. For example, using the GAJmage attribute, an application can give a 
Boopsi prop gadget (propgclass) an Image structure which the gadget uses as the imagery for its knob. This 
attribute is not "gettable" as there is no need for an application to have to ask the gadget for the structure that the 
application passed it in the first place. Whether or not a specific attribute is "gettable" is class dependent. For 
more information about the attributes of specific classes, see the Boopsi Class Reference in the Appendix B of 
this manual. 

What About the Boopsi Messages and Methods? 

According to the "OOP Overview" section, for an object to perform a method, something has to pass it a Boopsi 
message. The previous section discussed using Intuition functions to ask an object to do things like set and get 
attributes. The functions in the previous section seem to completely ignore all that material about methods and 
messages. What happened to the methods and messages? 
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Nothing-these functions don't ignore the OOP constructs, they just shield the programmer from them. Each of 
these functions corresponds to a Boopsi method: 

NewObject() OM_NEW 

DisposeObject() OM_DISPOSE 

SetAttrs()/SetGadgetAttrs() OM_SET 

GetAttr() OM_GET 

These methods are defined on the rootclass level, so all Boopsi classes inherit them. The Intuition functions that 
correspond to these methods take care of constructing and sending a Boopsi message with the appropriate 
method ID and parameters. 

The Public Classes 

Intuition contains 14 public classes, all of which are descendants of the rootclass. There are three primary 
classes that descend directly from rootclass: imageclass, gadgetclass, and icclass. 

The Imageclass Subclasses 

Normally, an application does not create an imageclass object. Instead, it will use a subclass of imageclass. 
Currently, there are four subclasses: frameiclass, sysiclass, fillrectclass, and itexticlass. 

frameiclass 

An embossed or recessed rectangular frame image, that renders itself using the proper Drawlnfo pens. 
This class is intelligent enough to bound or center its contents. 

sysiclass 

The class of system images. The class includes the images for the system and GadTools gadgets. 

fillrectclass 

A class of rectangle images that have frame and patternfill support. 

itexticlass 

A specialized image class used for rendering text. 

For more information on these classes see the Boopsi Class Reference in the Appendix B of this manual. It 
describes all of the existing public classes, their methods, and their attributes. 

The Gadgetclass Subclasses 

Like imageclass, applications do not normally create objects of gadgetclass, but instead create objects of its 
subclasses. Currently, gadgetclass has four subclasses: 

propgclass 

An easy to implement, horizontal or vertical proportional gadget. 

strgclass 

A string gadget. 

groupgclass 

A special gadget class that creates one composite gadget out of several others. 
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buttongclass 

A button gadget that keeps sending button presses while the user holds it down. 

buttongclass has a subclass of its own: 

frbuttonclass 

A buttongclass gadget that outlines its imagery with a frame. 



For specific information on these classes, see the Boopsi Class Reference in the Appendix B of this manual. 

Making Gadget Objects Talk to Each Other 

One use for a proportional gadget is to let the user change some integer value, like the red, green, and blue 
components of a color. This type of prop gadget is commonly accompanied by an integer string gadget, enabling 
the user to adjust one integer value by either typing the value into the string gadget or by scrolling the prop 
gadget. Because these two gadgets reflect the value of the same integer, when the user adjusts the state of one 
of the gadgets (and thus changing the integer value), the other gadget should automatically update to reflect the 
new integer value. 

When the user manipulates a conventional gadget, the gadget sends messages to an IDCMP port to indicate the 
state change (for information on IDCMP, see the "Intuition Input and Output Methods" chapter of this manual). To 
connect the string and prop gadgets from the previous paragraph, an application would have to listen for the 
IDCMP messages from two different gadgets, interpret the IDCMP message's meaning, and manually update the 
gadgets accordingly. Essentially, the application is responsible for "gluing" the gadgets together. This 
unnecessarily complicates an application, especially when that application already has to listen for and interpret 
many other events. 

Boopsi gadgets simplify this. By setting the appropriate attributes, an application can ask a Boopsi gadget to tell 
some other object when its state changes. One of the attributes defined by gadgetclass is ICA_TARGET (defined 
in <intuition/icclass.h>). The ICA_TARGET attribute points to another Boopsi object. When certain attributes in a 
Boopsi gadget change (like the integer value of a prop gadget), that gadget looks to see if it has an 
ICA_TARGET. If it does, it sends the target a message telling it to perform an OM_UPDATE method. 

The OM_UPDATE method is defined by rootclass. This is basically a special type of OM_SET method that is 
used specifically to tell a Boopsi object that another Boopsi object's state changed. Only Boopsi objects send 
OMJJPDATE messages. Note that standard classes of Boopsi gadgets only send out OMJJPDATE messages 
as a result of the user changing the state of the gadget (scrolling the prop gadget, typing a new number into an 
integer gadget, etc.). These gadgets do not send out OM_UPDATE messages when they receive OM_SET or 
OMJJPDATE messages. 

A Boopsi propgclass object has only one attribute that triggers it to send an OMJJPDATE request: PGAJTop. 
This attribute contains the integer value of the prop gadget. Every time the user moves a prop gadget, the 
PGAJTop attribute changes. If the prop gadget has an ICAJTARGET, the prop gadget will tell the target object 
that the PGAJTop value has changed. 

A Boopsi integer string gadget (a strgclass object) also has only one attribute that triggers it to send an 
OMJJPDATE request: STRINGA_LongVal. value contains the integer value of the integer string gadget. Like the 
prop gadget, if the integer string gadget has an ICAJTARGET, when the user changes the gadget's integer value 
(STRINGAjLongVal), the string gadget will tell the target object that the STRINGAjLongVal value has changed. 
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When a Boopsi gadget sends an OMJJPDATE message, it passes the ID of the attribute that changed plus that 
attribute's new value. For example, if the user typed a 25 into a Boopsi integer string gadget, that gadget would 
send an OMJJPDATE message to its ICAJTARGET saying in essence, "Hey, STRINGALongVal is 25". 

If this string gadget's ICAJTARGET is a propgclass object, the propgclass object will become confused because it 
has no idea what a STRINGAjLongVal attribute is. The string gadget needs to map its STRINGAjLongVal ID to 
the PGAJTop ID. This is what the ICAJMAP attribute is for. 

The ICAJMAP attribute is defined by gadgetclass (it is also defined for icclass-more on that later). It accepts a 
tag list of attribute mappings. When a gadget sends out an OMJJPDATE message, it uses this map to translate 
a specific attribute ID to another attribute ID, without changing the value of the attribute. Each Tagltem in the 
ICAJMAP makes up a single attribute mapping. The Tagltem.tiJTag of the mapping is the ID of an attribute to 
translate. The gadget translates that attribute ID to the attribute ID in Tagltem.tiJData. For example, an 
ICAJMAP that maps a string gadget's STRINGAjLongVal attribute to a prop gadget's PGAJTop attribute looks 
like this: 

struct Tagltem slidertostring [] = { 
{ PGAJTop , STRINGA_LongVal } , 
{ TAG_END , } 



}; 

Note that it is OK to have an ICA_TARGET without having an ICA_MAP. In cases where a gadget and its 
ICA_TARGET have a set of attributes in common, it would be unnecessary to use an ICA_MAP to match a 
gadget's attributes, as they already match. 

The following example, Talk2boopsi.c, creates a prop gadget and an integer string gadget which update each 
other without the example program having to process any messages from them. 

;/* Talk2boopsi .c - Execute me to compile me with SAS/C 5.10b 

LC -bl -cfistq -v -y -j73 Talk2boopsi .c 

Blink FROM LIB: c . o, Talk2boopsi . o TO Talk2boopsi LIBRARY LIB: LC. lib, LIB: Amiga. lib 

quit ;*/ 

/* This example creates a Boopsi prop gadget and integer string gadget, connecting them so they */ 

/* update each other when the user changes their value. The example program only initializes */ 

/* the gadgets and puts them on the window; it doesn't have to interact with them to make them */ 

/* talk to each other. */ 

#include <exec/types.h> 

#include <utility/tagitem.h> 

#include <intuition/intuition.h> 

#include <intuition/gadgetclass.h> /* contains IDs for gadget attributes */ 

#include <intuition/icclass.h> /* contains ICA MAP, ICA TARGET */ 

#include <clib/exec protos.h> 

#include <clib/intuition protos . h> 

#ifdef LATTICE /* Disable SAS/C CTRL/C handling */ 

int CXBRK(void) { return(O); } 
int chkabort (void) { return (0); } 
#endif 

UBYTE *vers = "\0$VER: Talk2boopsi 37.1"; 

struct Library *IntuitionBase; 
struct Window *w; 
struct IntuiMessage *msg; 
struct Gadget *prop, *integer; 

* The attribute mapping lists */ 

truct Tagltem prop2intmap [] = /* This tells the prop gadget to */ 

/* map its PGA Top attribute to */ 

{PGA Top, STRINGA LongVal}, /* STRINGA LongVal when it */ 

{TAG END,} /* issues an update about the */ 

; /* change to its PGA Top value. */ 

truct Tagltem int2propmap [] = /* This tells the string gadget */ 

/* to map its STRINGA LongVal */ 

{STRINGA LongVal, PGA Top} , /* attribute to PGA Top when it */ 

{TAG END,} /* issues an update. */ 

#define PROPGADGET_ID 1L 

#define INTGADGET ID 2L 

#define PROPGADGETWIDTH 10L 

#define PROPGADGETHEIGHT 80L 

#define INTGADGETHEIGHT 18L 

#define VISIBLE 10L 

#define TOTAL 100L 

#define INITIALVAL 2 5L 

#define MINWINDOWWIDTH 8 

#define MINWINDOWHEIGHT (PROPGADGETHEIGHT + 70) 

#define MAXCHARS 3L 

void main (void) 

{ 

BOOL done = FALSE; 

if (IntuitionBase = OpenLibrary ("intuition. library" , 37L) ) 

{ /* Open the window- -notice that the window's IDCMP port*/ 

/* does not listen for GADGETUP messages. */ 

if (w = OpenWindowTags (NULL, 

WA Flags, WFLG DEPTHGADGET | WFLG DRAGBAR | 



WFLG CLOSEGADGET | WFLG SIZEGADGET, 
WA IDCMP , IDCMP CLOSEWINDOW, 
WA MinWidth, MINWINDOWWIDTH, 
WA MinHeight, MINWINDOWHEIGHT, 
TAG END) ) 

/* Create a new propgclass object */ 
if (prop = (struct Gadget *) NewObject (NULL, "propgclass", 

GAID, PROPGADGET ID, /* These are defined by gadgetclass and */ 
GA Top, (w->BorderTop) + 5L, /* correspond to similarly named fields in */ 
GA Left, (w->BorderLef t) + 5L, /* the Gadget structure. */ 

GA Width, PROPGADGETWIDTH, 
GA Height, PROPGADGETHEIGHT, 

ICA MAP, prop2intmap, /* The prop gadget's attribute map */ 

/* The rest of this gadget's attributes are defined by propgclass. */ 

PGA Total, TOTAL, /* This is the integer range of the prop gadget.*/ 
PGA Top, INITIALVAL, /* The initial integer value of the prop gadget.*/ 

PGA Visible, VISIBLE, /*This determines how much of the prop gadget area is*/ 

/* covered by the prop gadget's knob, or how much of*/ 
/* the gadget's TOTAL range is taken up by the prop */ 
/* gadget's knob. */ 

PGA NewLook, TRUE, /* Use new-look prop gadget imagery */ 
TAG END) ) 
{ /* create the integer string gadget. */ 

if (integer = (struct Gadget *) NewObject (NULL, "strgclass", 

GAID, INTGADGET ID, /* Parameters for the Gadget structure*/ 

GA Top, (w->BorderTop) + 5L, 

GA Left, (w->BorderLeft) + PROPGADGETWIDTH + 10L, 

GA Width, MINWINDOWWIDTH - 

(w->BorderLef t + w->BorderRight + 
PROPGADGETWIDTH + 15L) , 
GA Height, INTGADGETHEIGHT, 

ICA MAP, int2propmap, /* The attribute map */ 

ICA TARGET, prop, /* plus the target. */ 

/* Th GA Previous attribute is defined by gadgetclass and is used to*/ 

/* wedge a new gadget into a list of gadget's linked by their */ 

/* Gadget . NextGadget field. When NewObject () creates this gadget, */ 

/* it inserts the new gadget into this list behind the GA Previous */ 

/* gadget. This attribute is a pointer to the previous gadget */ 

/* (struct Gadget *) . This attribute cannot be used to link new */ 

/* gadgetsinto the gadget list of an open window or requester, */ 

GA Previous, prop, /* use AddGListO instead. */ 

STRINGA LongVal, INITIALVAL, /* These attributes are defined by 

strgclass. */ 
STRINGA MaxChars, MAXCHARS, /* The first contains the value of the */ 
TAG END) ) /* integer string gadget. The second is the */ 

/* maximum number of characters the user is */ 
/* allowed to type into the gadget. */ 

{ 

SetGadgetAttrs (prop, w, NULL, /*Because the integer string gadget did not*/ 
ICA TARGET, integer, /* exist when this example created the prop*/ 
TAG END) ; /* gadget, it had to wait to set the */ 

/* ICA Target of the prop gadget. */ 

AddGList(w, prop, -1, -1, NULL); /* Add the gadgets to the */ 

Ref reshGList (prop, w, NULL, -1); /* window and display them. */ 

while (done == FALSE) /* Wait for the user to click */ 
{ /* the window close gadget. */ 

WaitPort ( (struct MsgPort *)w->UserPort) ; 

while (msg = (struct IntuiMessage *) 

GetMsg( (struct MsgPort *) w->UserPort) ) 

{ 

if (msg->Class == IDCMP CLOSEWINDOW) 

done = TRUE; 
ReplyMsg (msg) ; 



} 
} 

RemoveGList (w, prop, -1); 
DisposeObject (integer) ; 

} 
DisposeObject (prop) ; 

} 
CloseWindow(w) ; 

} 

CloseLibrary (IntuitionBase) ; 

} 
} 

Making Gadgets Talk to an Application 

There are two questions that the example above brings to mind. The first is, "What happens if the user types a 
value into the string gadget that is beyond the bounds of the prop gadget?" The answer is simple: very little. The 
prop gadget is smart enough to make sure its integer value does not go beyond the bounds of its display. In the 
example, the prop gadget can only have values from to 90. If the user tries to type a value greater than 90, the 
prop gadget will set itself to its maximum of 90. Because the integer string gadget doesn't have any bounds 
checking built into it, the example needs to find an alternative way to check the bounds. 

The other question is, "How does talk2boopsi.c know the current value of the gadgets?" That answer is simple 
too: it doesn't. The example doesn't ask the gadgets what their current values are (which it would do using 
GetAttr() and the example doesn't pay attention to gadget events at the window's IDCMP port, so it isn't going to 
hear about them. 

One easy way to hear about changes to the gadget events is to listen for a "release verify". Conventional Intuition 
gadgets can trigger a release verify IDCMP event when the user finishes manipulating the gadget. Boopsi 
gadgets can do this, too, while continuing to update each other. 

To make Talk2boopsi.c6o this would require only a few changes. First, the window's IDCMP port has to be set up 
to listen for IDCMP_GADGETUP events. Next, the example needs to set the gadget's GACT_RELVERIFY flags. 
It can do this by setting the gadgetclass GA_RelVerify attribute to TRUE for both gadgets. That's enough to 
trigger the release verify message, so all Talk2boopsi.c needs to do is account for the new type of IDCMP 
message, IDCMP_GADGETUP. When Talk2boopsi.c gets a release verify message, it can use GetAttr() to ask 
the integer gadget its value. If this value is out of range, it should explicitly set the value of the integer gadget to a 
more suitable value using SetGadgetAttrs(). 
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Using the GACT_RELVERIFY scheme above, an application will only hear about changes to the gadgets after the 
user is finished changing them. The application does not hear all of the interim updates that, for example, a prop 
gadget generates. This is useful if an application only needs to hear the final value and not the interim update. 

It is also possible to make the IDCMP port of a Boopsi gadget's window the ICA_TARGET of the gadget. There is 
a special value for ICA_TARGET called ICTARGETJDCMP (defined in <intuition/icclass.h>). This tells the gadget 
to send an IDCMPJDCMPUPDATE class IntuiMessage to its window's IDCMP port. Of course, the window has 
to be set up to listen for IDCMPJDCMPUPDATE IntuiMessages. The Boopsi gadget passes an address in the 
IntuiMessage. lAddress field. It points to an attribute tag list containing the attribute (and its new value) that 
triggered the IDCMPJDCMPUPDATE message. An application can use the utility.library tag functions to access 
the gadget's attributes in this list. Using this scheme, an application will hear all of the interim gadget updates. If 
the application is using a gadget that generates a lot of interim OMJJPDATE messages (like a prop gadget), the 
application should be prepared to handle a lot of messages. 

Using this IDCMPJDCMPUPDATE scheme, if the gadget uses an ICAJvlAP to map the attribute to a special 
dummy attribute ICSPECIAL_CODE (defined in <intuition/icclass.h>), the IntuiMessage. Code field will contain 
the value of the attribute. Because the attribute's value is a 32-bit quantity and the IntuiMessage. Code field is 
only 16 bits wide, only the least significant 16 bits of the attribute will appear in the IntuiMessage. Code field, so it 
can't hold a 32-bit quantity, like a pointer. Applications should only use the lower 1 6 bits of the attribute value. 

The Interconnection Classes 

The IDCMPJDCMPUPDATE scheme presents a problem to an application that wants to make gadgets talk to 
each other and talk to the application. Boopsi gadgets only have one ICAJTARGET. One Boopsi gadget can talk 



to either another Boopsi object or its window's IDCMP port, but not both. Using this scheme alone would force the 
application to update the integer value of the gadgets, which is what we are trying to avoid in the first place. 

One of the standard Boopsi classes, icclass, is a class of information forwarders. An icclass object receives 
OMJJPDATE messages from one object and passes those messages on to its own ICA_TARGET. If it needs to 
map any incoming attributes, it can use its own ICA_MAP to do so. 

Icclass has a subclass called modelclass. Using a modelclass object, an application can chain a series of these 
objects together to set up a "broadcast list" of icclass objects. The modelclass object is similar to the icclass 
object in that it has its own ICA_TARGET and ICA_MAP. It differs in that an application can use the modelclass 
OM_ADDMEMBER method to add icclass objects to the modelclass object's broadcast list. 

The OM_ADDMEMBER method is defined by rootclass. It adds one Boopsi object to the personal list of another 
Boopsi object. It is up to the Boopsi object's class to determine the purpose of the objects in the list. Unlike the 
other methods mentioned so far in this chapter, OM_ADDMEMBER does not have an Intuition function 
equivalent. To pass an OM_ADDMEMBER message to an object use the amiga.lib function DoMethodA(), or its 
stack-based equivalent, DoMethod(): 

ULONG DoMethodA( Object *myobject, Msg boopsimessage); 
ULONG DoMethod (Object *myobject, ULONG methodID, ...); 

The return value is class-dependent. The first argument to both of these functions points to the object that will 
receive the Boopsi message. 
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For DoMethod A(), boopsimessage is the actual Boopsi message. The layout of it depends on the method. 
Every method's message starts off with an Msg (from <intuition/classusr.h>): 

typedef struct { 

ULONG MethodID; /* Method-specific data may follow this field */ 
} *Msg; 

The message that the OM_ADDMEMBER method uses looks like this (from <intuition/classusr.h>): 

struct opMember { 

ULONG MethodID; 
Object *opam_Object ; 

}; 
where MethodID is OMADDMEMBER and opam Object points to the object to add to myobject's list. 

DoMethod() uses the stack to build a message. To use DoMethod(), just pass the elements of the method's 
message structure as arguments to DoMethod() in the order that they appear in the structure. For example, to 
ask the Boopsi object myobject to add the object addobject to its personal list: 

DoMethod (myobject, OM_ADDMEMBER , addobject); 

To rearrange Talk2boopsi.c so that it uses a modelclass object (also known as a model): 

Create the integer and prop gadget. 

Create the model. 

Create two icclass objects, one called int2prop and the other called prop2int. 

Make the model the ICA_TARGET of both the integer gadget and the prop gadget. The gadgets do not 
need an ICA_MAP. 

Using DoMethodQ to call OM_ADDMEMBER, add the icclass objects to the model's personal list. 

Make the prop gadget the ICA_TARGET of int2prop. Make the integer gadget the ICA_TARGET of 
prop2int. 



Create an ICA_MAP map list for int2prop that maps STRINGA_LongVal to PGA_Top. Create an 
ICA_MAP map list for prop2int that maps PGA_Top to STRINGA_LongVal. Make the ICA_TARGET of 
the model ICTARGETJDCMP. 
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Diagrammatically, the new Talk2boopsi.c should look something like this: 
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When either of these gadgets has some interim state change (caused by the user manipulating the gadgets), it 
sends an OM_UPDATE message to its ICA_TARGET, which in this case is the modelclass object. When this 
model gets the message, it does two things. It sends an IDCMPJDCMPUPDATE to the IDCMP port of the 
gadget's window and it also sends OM_UPDATE messages to all of the objects in its personal list. When 
int2prop gets an OMUPDATE message, it forwards that message to its ICATARGET, the prop gadget. 
Similarly, when prop2int gets an OMUPDATE message, it forwards that message to its ICATARGET, the 
integer gadget. 

Although in this case it isn't a problem, icclass and modelclass objects contain loop inhibition capabilities. If an 
icclass object (or modelclass object) receives an OMJJPDATE message, it forwards the message to its target. If 
somehow that forwarded message gets forwarded (or broadcast) back to the icclass object, the icclass object 
ignores the message. This prevents the possibility of an infinite OM_UPDATE loop. 
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Creating a Boopsi Class 



So far this chapter has only hinted at what is possible with Boopsi. Its power lies in its extensibility. Boopsi grants 
the application programmer the power to add custom features to existing classes. If an existing class comes 
close to your needs, you can build on that class so it does exactly what you want. If you want a class that is 
unlike an existing class, you can create it. 

The heart of a Boopsi class is its method Dispatcher function. According to the OOP metaphor, when an 
application wants a Boopsi object to perform a method, it sends the object a message. In reality, that object is 
only a data structure, so it does not have the power to do anything. When an object receives a Boopsi message, 
a Boopsi message structure is passed to the dispatcher of that object's class. The dispatcher examines the 
message and figures out what to do about it. 



For example, when an application calls SetGadgetAttrsQ on an integer gadget: 



SetGadgetAttrs (myintegergadget , mywindow, NULL, 

STRINGA_LongVal , 75L, 

GA_ID, 2L, 
TAG_END) ) ; 

the SetGadgetAttrs() function calls the strgclass dispatcher. A Boopsi dispatcher receives three arguments: a 
pointer to the dispatcher's Class (defined in <intuition/classes.h>), a pointer to the object that is going to perform 
the method, and a pointer to the Boopsi message. In this case, the SetGadgetAttrs() function builds an 
OM_SET message, finds the strgclass dispatcher, and "sends" the dispatcher the OMSET message. 
SetGadgetAttrs() can find the dispatcher because an object contains a reference to its dispatcher. 

When the dispatcher function "gets" the message, it examines the message to find out its corresponding method. 
In this case, the dispatcher recognizes the message as an OM_SET message and proceeds to set 
myintegergadget's attributes. 

An OM_SET message looks like this (defined in <intuition/classusr.h>): 

struct opSet { 

ULONG MethodID; /* This will be set to OM_SET */ 

struct Tagltem *ops_AttrList ; /* A tag list containing the */ 

/* attribute/value pairs of */ 

/* the attributes to set. */ 
struct Gadgetlnfo *ops_GInfo; /* Special information for gadgets */ 
} 

The OM_SET message contains a pointer to a tag list in ops_AttrList that looks like this: 

{STRINGA_LongVal, 75L}, 
{GA_ID, 2L}, 
{TAG_END, } 

The strgclass dispatcher scans through this tag list and recognizes the STRINGA_LongVal attribute. The 
dispatcher sets myintegergadget's internal STRINGA_LongVal value to the corresponding value (75L) from the 
attribute/value pair. 
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The strgclass dispatcher continues to scan through the tag list. When it finds GAJD, it does not process it like 
STRINGA_LongVal. The strgclass dispatcher's OM_SET method does not recognize the GAJD attribute 
because strgclass inhehtedXhe GAJD attribute from gadgetclass. To handle setting the GAJD attribute, the 
strgclass dispatcher passes on the OM_SET message to its superclass's dispatcher. The strgclass dispatcher 
passes control to the gadgetclass dispatcher, which knows about the GAJD attribute. 

Building On Existing Public Classes 

A program can create its own subclasses which build on the features of existing classes. For example, a program 
could create a subclass of modelclass named rkmmodelclass. Rkmmodelclass builds on modelclass by adding a 
new attribute called RKMMOD_CurrVal. This purpose of this attribute is simply to hold an integer value. 

Because this new attribute is built into an rkmmodel object, the object could be implemented so that it exercises a 
certain amount of control over that value. For example, rkmmodelclass could be implemented so an rkmmodel 
performs bounds checking on its internal value. When an application asks an rkmmodel to set its internal 
RKMMOD_CurrVal, the rkmmodel makes sure the new value is not beyond a maximum value. If the new value is 
beyond the maximum, it sets its current value to the maximum. After the rkmmodelclass object has set its internal 
RKMMOD_CurrVal, it can broadcast the change on to objects in its broadcast list. 

The dispatcher for rkmmodelclass does not have to do a lot of work because it inherits most of its behavior from 
its superclasses. The rkmmodelclass has to take care of setting aside memory for the RKMMOD_CurrVal 
attribute and processing any OM_SET requests to set the RKMMOD_CurrVal attribute. For any other attributes or 
methods, the rkmmodelclass dispatcher passes on processing to its superclass, modelclass. 

Building Rkmmodelclass 

So far, the theoretical class rkmmodelclass has just one attribute, RKMMOD_CurrVal. A couple of extra attributes 



can make it more useful. Because the rkmmodel object maintains an upper limit on its RKMMOD_CurrVal integer 
value, it would be useful if that upper limit was variable. Using a new attribute, RKMMODJJmit, an application 
can tell a rkmmodel what its upper limit is. The rkmmodel will enforce the limit internally, so the application 
doesn't have to worry about it. 

Another useful addition is a pulse increment and decrement for RKMMOD_CurrVal. Whenever the model 
receives an increment or decrement command, it increments or decrements its internal value. To make the 
example class simple, rkmmodelclass implements incrementing and decrementing by creating "dummy" attributes 
called RKMMODJJp and RKMMOD_Down. When an rkmmodel receives an OM_SET message for one of these 
attributes, it increments or decrements RKMMOD_CurrVal. An rkmmodelclass object does not care what the 
value of the RKMMODJJp and RKMMOD_Down attributes are, it only cares that it received an OMJJPDATE 
about it. 

There are two pieces of data that make up this new class's instance data: the rkmmodel's current value 
(RKMMOD_CurrVal) and the upper limit of the rkmmodel (RKMMOD_Limit). The example class consolidates 
them into one structure: 

struct RKMModData { 
ULONG currval; 
ULONG val limit; 

}; 
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Writing the Dispatcher 

The C prototype for a Boopsi dispatcher looks like this: 

ULONG dispatchRKMModel (Class *cl, Object *recvobject, Msg msg) ; 

where cl points to the Class (defined in <intuition/classes.h>) of the dispatcher, recvobject points to the object 
that received the message, and msg is that Boopsi message. The format of the message varies according to the 
method. The default Boopsi message is an Msg (from <intuition/classusr.h>): 

typedef struct { 

ULONG MethodID; 
} *Msg; 

Boopsi methods that require parameters use custom message structures. The first field of any message structure 
is always the method's methodlD. This makes custom messages look like an Msg. The dispatcher looks at an 
incoming message's first field to tell what its method is. Rkmmodelclass objects respond to several rootclass 
methods: 

OM_NEW 

This method creates a new rkmmodelclass object. It uses an opSet structure as its Boopsi message. 

OM_DISPOSE 

This method tells an object to dispose of itself. It uses an Msg as its Boopsi message. 

OM_SET 

This method tells an object to set one or more of its attribute values. It uses an opSet structure as its 
Boopsi message. 

OMJJPDATE 

This method tells an object to update one or more of its attribute values. It uses an opUpdate structure 
as its Boopsi message. 

OM_GET 

This method tells an object to report an attribute value. It uses an opGet structure as its Boopsi 
message. 

OM_ADDTAIL 

This method tells an object to add itself to the end of an Exec list. It uses an opAddTail structure as its 
Boopsi message. 



OM_REMOVE 

This method tells an object to remove itself from an Exec list. It uses an Msg as its Boopsi message. 

OM_ADDMEMBER 

This method tells an object to add an object to its broadcast list. It uses an opMember structure as its 
Boopsi message. 

OM_REMMEMBER 

This method tells an object to remove an object from its broadcast list. It uses an opMember structure 
as its Boopsi message. 

OM_NOTIFY 

This method tells an object to broadcast an attribute change to its broadcast list. It uses an opSet 
structure as its Boopsi message. 

Of these, rkmmodelclass has to process OM_NEW, OM_SET, OMJJPDATE, and OM_GET. 

Boopsi - Object Oriented Intuition 307 

OM_NEW 

The OM_NEW method returns a pointer to a newly created Boopsi object, or NULL if it failed to create the object. 
This method receives the following message structure (defined in <\ntuition/classusr.h>): 

/* The OM_NEW method uses the same structure as OM_SET */ 

struct opSet { 

ULONG MethodID; 

struct Tagltem *ops_AttrList ; 
struct Gadgetlnfo *ops_GInfo; 

} ; 

The ops_AttrList field contains a pointer to a Tagltem array of attribute/value pairs. These contain the initial 
values of the new object's attributes. The ops_Glnfo field is always NULL for the OM_NEW method. 

Unlike other methods, when a dispatcher gets an OM_NEW message, the object pointer (recvobject from the 
dispatchRKMModelQ prototype above) does not point to an object. It doesn't make sense for recvobject to 
point to an object because the idea is to create a new object, not act on an existing one. 

The pointer normally used to pass a Boopsi object is instead used to pass the address of the object's "true class". 
An object's true class is the class of which the object is an instance. 

The first thing the dispatcher does when it processes an OM_NEW message is pass the OM_NEW message on 
to its superclass's dispatcher. It does this using the amiga.lib function DoSuperMethodAQ: 

ULONG DoSuperMethodA (Class *cl, Object *trueclass, Msg msg) ; 

Each dispatcher passes control to its superclass. Eventually the message will arrive at the rootclass dispatcher. 
The OM_NEW method in the rootclass dispatcher looks at the object's true class (trueclass from the prototype) 
to find out which class dispatcher is trying to create a new object. Note that trueclass is not necessarily the same 
as the current dispatcher's class (cl from the dispatchRKMModel() prototype above), although this would be the 
case if the object's true class is a subclass of the current dispatcher's class. 

The rootclass dispatcher uses the true class to find out how much memory to allocate for the object's instance 
data. Each class keeps a record of how much memory its local instance data requires. The rootclass dispatcher 
also looks at each class between the true class and rootclass to find out much memory the local instance data for 
those classes require. The rootclass dispatcher totals the amount of local instance data memory needed by the 
true class and each of its superclasses and allocates that much memory. 

If all goes well, the rootclass dispatcher increments a private field in the true class that keeps track of how many 
instances of the true class there currently are. It then returns a pointer to the newly created object and passes 
control back to the subclass dispatcher that called it, which is icclass in the case of rkmmodelclass. If there was a 
problem, the rootclass dispatcher does not increment the object count and passes back a NULL. 



When the rootclass dispatcher returns, the icclass dispatcher regains control from DoSuperMethodAQ. 
DoSuperMethodA() will return either a pointer to the new object or else it returns NULL if there was an error. 
Although the rootclass dispatcher allocated all the memory the object needs, it only initialized the instance data 
local to rootclass. Now it's the icclass dispatcher's turn to do some work. It has to initialize the instance data that 
is local to icclass. 
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A dispatcher finds its local instance data by using the INST_DATA() macro (defined in <intuition/classes.h>): 

void *INST_DATA (Class *localclass, Object *object); 

INST_DATA() takes two arguments, a pointer to a class and a pointer to the object. The INST_DATA() macro 
returns a pointer to the instance data local to localclass. When the icclass dispatcher was called, it received 
three arguments, one of which was a pointer to the local class (icclass). The icclass dispatcher passes this pointer 
and the new object pointer it got from DoSuperMethodAQ to INST_DATA() to get a pointer to the instance data 
local to icclass. 

After initializing its local instance data, the icclass dispatcher passes control back to the modelclass dispatcher, 
which in turn, initializes the instance data local to modelclass. Finally, the rkmmodelclass dispatcher regains 
control and now has to take care of its local instance data. 

To find its local instance data, the rkmmodelclass dispatcher needs a pointer to its Class and a pointer to the new 
object. The dispatcher function gets its Class pointer as its first argument (cl from the dispatchRKMModel() 
prototype above). It gets the new object pointer as the return value from DoSuperMethodAQ. In this case, 
INST DATA() returns a pointer to an RKMModData structure. 

Now the dispatcher has to initialize its local instance data. It has to scan through the tag list passed in the 
OM_NEW message looking for initial values for the RKMMOD_CurrVal and RKMMODJJmit attributes. As an 
alternative, the dispatcher's OM_NEW method can use its OM_SET method to handle initializing these "settable" 
attributes. 

Finally, the dispatcher can return. When the dispatcher returns from an OM_NEW method, it returns a pointer to 
the new object. 

If the OM_NEW method fails, it should tell the partially initialized object it got from its superclass's dispatcher to 
dispose of itself (using OM_DISPOSE) and return NULL. 

OM_SET/OM_UPDATE 

For the OM_SET message, the rkmmodelclass dispatcher steps through the attribute/value pairs passed to it in 
the OM_SET message looking for the local attributes (see OM_NEW for the OM_SET message structure). The 
RKMMODJJmit attribute is easy to process. Just find it and record the value in the local RKMModData. vallimit 
field. 

Because the function of the rkmmodelclass's OM_SET and OM_UPDATE methods are almost identical, the 
rkmmodelclass dispatcher handles them as the same case. The only difference is that, because the 
OM_UPDATE message comes from another Boopsi object, the OM_UPDATE method can report on transitory 
state changes of an attribute. For example, when the user slides a Boopsi prop gadget, that prop gadget sends 
out an interim OM_UPDATE message for every interim value of PGA_Top. When the user lets go of the prop 
gadget, the gadget sends out a final OMJJPDATE message. The OM_UPDATE message is almost identical to 
the OMSET message: 

#define OPUF_INTERIM (1<<0) 

/* the OM_NOTIFY method uses the same structure */ 

struct opUpdate { 

ULONG MethodID; 

struct Tagltem *opu_AttrList ; 

struct Gadgetlnfo *opu_GInfo; 

ULONG opu_Flags; /* The extra field */ 

}; 



Boopsi - Object Oriented Intuition 309 

A dispatcher can tell the difference between an interim and final OM_UPDATE message because the 
OMJJPDATE message has an extra field on it for flags. If the low order bit (the OPUFJNTERIM bit) is set, this is 
an interim OMJJPDATE message. The interim flag is useful to a class that wants to ignore any transitory 
messages, processing only final attribute values. Because rkmmodelclass wants to process all changes to its 
attributes, it processes all OMJJPDATE messages. 

The RKMMOD_CurrVal attribute is a little more complicated to process. The dispatcher has to make sure the new 
current value is within the limits set by RKMMODJ_imit, then record that new value in the local 
RKMModData.currval field. Because other objects need to hear about changes to RKMMOD_CurrVal, the 
dispatcher has to send a notification request. It does this by sending itself an OMJMOTIFY message. The 
OMJMOTIFY message tells an object to notify its targets (its ICAJTARGET and the objects in its broadcast list) 
about an attribute change. The OMJMOTIFY method does this by sending OMJJPDATE messages to all of an 
object's targets. 

The rkmmodelclass dispatcher does not handle the OMJMOTIFY message itself. It inherits this method from 
modelclass, so the rkmmodelclass dispatcher passes OMJMOTIFY messages on to its superclass. To notify its 
targets, the rkmmodelclass dispatcher has to construct an OMJMOTIFY message. The OMJMOTIFY method 
uses the same message structure as OMJJPDATE. Using the stack-based version of DoSuperMethodAQ, 
DoSuperMethodQ, the dispatcher can build an OMJMOTIFY message on the stack: 



struct Tagltem tt [2] ; 
struct opUpdate *msg; 

tt[0] .ti_Tag = RKMMOD_CurrVal ; /* make a tag list. */ 
tt [0] .ti_Data = mmd->currval; 
tt[l].ti_Tag = TAG_END; 

DoSuperMethod (cl, o, OM_NOTIFY, tt, msg->opu GInfo, 

( (msg->MethodID == OMJJPDATE) ? (msg->opu_Flags) : 0L) ) ; 

Because the OMJMOTIFY needs a tag list of attributes about which to issue updates, the dispatcher builds a tag 
list containing just the RKMMOD_CurrVal tag and its new value. The dispatcher doesn't use the tag list passed to 
it in the OMJJPDATE/OMJMOTIFY message because that list can contain many other attributes besides 
RKMMOD_CurrVal. 

The msg variable in the DoSuperMethodQ call above is the OMJ3ET or OMJJPDATE message that was 
passed to the dispatcher. The dispatcher uses that structure to find a pointer to the Gadgetlnfo structure that the 
OMJMOTIFY message requires. The Gadgetlnfo structure comes from Intuition and contains information that 
Boopsi gadgets need to render themselves. For the moment, don't worry about what the Gadgetlnfo structure 
actually does, just pass it on. The targets of an rkmmodel will probably need it. 

Notice that the dispatcher has to test to see if the message is an OMJ3ET or OMJJPDATE so it can account for 
the opuJ=lags field at the end of the OMJJPDATE message. 

Processing the RKMMODJJp and RKMMODJDown attributes is similar to the RKMMOD_CurrVal attribute. 
When the dispatcher sees one of these, it has to increment or decrement the local RKMModData.currval, 
making sure RKMModData.currval is within limits. The dispatcher then sends an OMJMOTIFY message to the 
superclass about the change to RKMModData.currval. 
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The return value from the dispatcher's OMJ3ET method depends on the what effect the attribute change has to 
the visual state of the objects in the rkmmodel's broadcast list. If an attribute change will not affect the visual state 
of the rkmmodel's objects, the OMJ3ET method returns zero. If the attribute change could trigger a change to the 
rkmmodel's objects, it returns something besides zero. For example, the rkmmodelclass OMJ3ET method returns 
1L if an rkmmodel's RKMMOD_CurrVal, RKMMODJJp, or RKMMODJDown attribute is changed. 



At some point the rkmmodelclass dispatcher has to allow its superclasses to process these attributes it inherits. 
Normally a dispatcher lets the superclass process its attributes before attempting to process any local attributes. 
The rkmmodelclass dispatcher does this by passing on the OM_SET or OM_UPDATE message using 
DoSuperMethodA() (inheritance at work!). As an alternative, the dispatcher can use the amiga.lib function 
SetSuperAttrs(). See the amiga.lib Autodocs for more details on this function. 

OM_GET 

The rkmmodel only has one "gettable" attribute: RKMMOD_CurrVal, which makes processing it easy. The 
OM_GET message looks like this (defined in <intuition/classusr.h>): 

struct opGet { 

ULONG MethodID; /* OM_GET */ 

ULONG opg_AttrID; /* The attribute to retrieve */ 

ULONG *opg_Storage; /* a place to put the attribute's value */ 

}; 

When the rkmmodelclass dispatcher receives an OM_GET message with an opg_AttrlD equal to 
RKMMOD_CurrVal, it copies the current value (RKMModData.currval) to the memory location opg_Storage 
points to and returns a value of TRUE. The TRUE indicates that there was no error. If opg_AttrlD is not 
RKMMOD_CurrVal, the dispatcher should let its superclass handle this message. 

The rkmmodelclass dispatcher can take advantage of the fact that the only "gettable" attribute available to an 
rkmmodel is RKMMOD_CurrVal (the attributes defined by modelclass and icclass are not gettable-see the 
Boopsi Class Reference in the Appendix B of this manual for more details on which attributes are "settable", 
"gettable", etc.). If opg_AttrlD is not RKMMOD_CurrVal, the rkmmodelclass dispatcher can return FALSE, 
indicating that the attribute was not "gettable". 

If the rkmmodelclass dispatcher comes across any other messages besides OM_NEW, OM_SET, OM_UPDATE, 
and OM_GET message, it blindly passes them on to its superclass for processing. 

Making the New Class 

The Intuition function MakeClassi creates a new Boopsi class: 

Class *MakeClass (UBYTE *newclassID, UBYTE *pubsuperclassID, 
Class *privsuperclass, UWORD instancesize, 
ULONG flags) ; 

If the new class is going to be public, newclassID is a string naming the new class. If the new class is private, 
this field is NULL. The next two fields tell MakeClassQ where to find the new class's superclass. If the 
superclass is public, pubsuperclassID points to a string naming that public superclass and the privsuperclass 
pointer is NULL. If the superclass is private, privsuperclass points to that superclass's Class structure and 
pubsuperclassID is NULL. The size of the new class's local instance data is instancesize. The last parameter, 
flags, is for future enhancement. For now, make this zero. 

Boopsi - Object Oriented Intuition 31 1 

If it is successful, MakeClass() returns a pointer to the new class, otherwise it returns NULL. When MakeClass() 
is successful, it also takes measures to make sure no one can "close" the new class's superclass (using 
FreeClass()). It does this by incrementing a private field of the superclass that keeps track of how many 
subclasses the superclass currently has. 

After successfully creating a class, an application has to tell the class where its dispatcher is. The Class pointer 
(defined in <intuition/classes.h>) returned by MakeClassQ contains a Hook structure called cl_Dispatcher, 
which is used to call the dispatcher. The application has to initialize this hook: 

myclass->cl_Dispatcher .h_Entry = HookEntry; 
/* HookEntry () is defined in amiga.lib */ 

myclass->cl_Dispatcher .h_SubEntry = dispatchRKMModel ; 

The hEntry field points to a function in amiga.lib that copies the function arguments to where the dispatcher 
expects them. See the "Callback Hooks" section of the "Utility Library" chapter of this manual for more details. 



To make a class public instead of private, an application has to call AddClassQ in addition to giving the class a 
name in MakeClassQ. AddClassQ takes one argument, a pointer to a valid Class structure that has been 
initialized as a public class by MakeClass(). To remove a public class added to the system with AddClass(), 
pass the public class pointer to RemoveClass(). See the Intuition Autodocs for more details on AddClassQ and 
RemoveClassQ. 

RKMModel.c 

The following code, RKMModel.c, makes up an initialization function and the dispatcher function for a private 
class informally called rkmmodelclass. 

; /* RKMModel . c - A simple custom modelclass subclass . 
LC -cfist -bl -y -v - j73 rkmmodel . c 
quit ;*/ 

#include < exec /types .h> 
#include < intui t ion/ intuit ion. h> 
#include < intuition/classes .h> 
#include < intui tion/classusr .h> 
#include < intuit ion/ imaged ass .h> 
#include < intui tion/gadgetclass .h> 
#include < intui tion/cghooks .h> 
#include < intuit ion/ icclass .h> 
#include <utility/tagitem.h> 
#include <utility /hooks .h> 
#include <clib/ intui tionprotos .h> 
#include <clib/utility_protos .h> 
#include <clib/alib_protos .h> 
#include <clib/alib_stdio_protos .h> 

extern struct Library * Intui tionBase, *UtilityBase; 

/************************************************ 

/**************** The attributes defined by this class *****************************************/ 

#define RKMMODCurrVal (TAGUSER + 1) /* This attribute is the current value of the model.*******/ 

#define RKMMODUp (TAGUSER + 2) /* These two are fake attributes that rkmmodelclass *******/ 
#define RKMMODDown (TAGUSER + 3} /* uses as pulse values to increment/decrement the *******/ 

/* rkmmodel's RKMMODCurrVal attribute. *******/ 

#define RKMMODLimit (TAGUSER + 4} /* This attribute contains the upper bound of the *******/ 

/* rkmmodel's RKMMODCurrVal . The rkmmodel has a *******/ 
/* static lower bound of zero. *******/ 

#define DEFAULTVAL LIMIT 100L /* If the programmer doesn't set */ 

/* RKMMODLimit, it defaults to this. */ 

struct RKMModData { 

ULONG currval; /* The instance data for this class. */ 

ULONG vallimit; 

}; 

/************************** The functions in this module ********************************/ 

void geta4 (void) ; /***************/ 

Class *initRKMModClass{void) ; /***************/ 

BOOL f reeRKMModClass (Class *} ; /***************/ 

ULONG dispatchRKMModel (Class *, Object *, Msg) ; /***************/ 

void NotifyCurrVal (Class *, Object *, struct opUpdate *, struct RKMModData *} ; /***************/ 
/********************************************* 

/******************************** Initialize the class **************************************/ 

Class *initRKMModClass (void) /* Make the class and set */ 

{ /* up the dispatcher' s hook. */ 

Class *cl; 

extern ULONG HookEntry ( ) ; /* < defined in amiga.lib. */ 

if ( cl = MakeClass( NULL, 

"modelclass" , NULL, 

sizeof ( struct RKMModData ) , 

)) 

{ 

cl->cl_Dispatcher .hEntry = HookEntry; /* initialize the */ 

cl->cl_Dispatcher .hSubEntry = dispatchRKMModel; /* clDispatcher */ 



/* Hook. 

} 

return { cl ) ; 



} 



/********************************* Free the class ***************************************/ 

BOOL freeRKMModClass( Class *cl ) 

{ 

return (FreeClass (cl) ) ; 

} 

/******************************** The clas s Di spatcher ***********************************/ 

ULONG dispatchRKMModel (Class *cl. Object *o, Msg msg) 

{ 

struct RKMModData *mmd; 

APTR retval = NULL; /* A generic return value used by this class's methods. The */ 

/* meaning of this field depends on the method. For example, */ 

/* OMGET uses this a a boolean return value, while OMNEW */ 

/* uses it as a pointer to the new object. */ 

geta4{); /* SAS/C and Manx function - makes sure A4 contains global data pointer. */ 

switch {msg->MethodID) 

{ 

case OMNEW: /* Pass message onto superclass first so it can set aside the memory */ 
/* for the object and take care of superclass instance data. */ 

if {retval = (APTR) DoSuperMethodA(cl, o, msg)) 
f /************************************************* 

/* For the OMNEW method, the object pointer passed to the dispatcher */ 

/* does not point to an object (how could it? The object doesn' t exist */ 

/* yet.) DoSuperMethodA() returns a pointer to a newly created */ 

/* object. INST_DATA( ) is a macro defined in < intuition/ classes .h> */ 

/* that returns a pointer to the object' s instance data that is local */ 

/* to this class . For example, the instance data local to this class */ 

/* is the RKMModData structure defined above. */ 

mmd = INST_DATA(cl, retval); 

mmd->currval = GetTagData (RKMMODCurrVal, OL, /* initialize object's attributes. */ 

( (struct opSet *)msg) ->ops_AttrList) ; 
mmd->vallimit = GetTagData (RKMMODLimit, DEFAULTVALLIMIT, 

( (struct opSet *)msg) ->ops_AttrList) ; 

} 

break; 
case OMSET: 
case OMUPDATE: 

mmd = INST_DATA(cl, o) ; 

DoSuperMethodA (cl, o, msg) ; /* Let the superclasses set their attributes first . */ 

{ 

struct Tagltem *tstate, *ti; /* grab some temp variables off of the stack. */ 

ti = ( (struct opSet *)msg) ->ops_AttrList; 
tstate = ti; 

/* Step through all of the at tribute/ value pairs in the list. Use the */ 
/* utility. library tag functions to do this so they can properly process */ 
/* special tag IDs like TAGSKIP, TAGIGNORE, etc. */ 

while (ti = NextTagItem(&tstate) ) /* Step through all of the attribute/value */ 

{ /* pairs in the list. Use the utility. library tag functions */ 

/* to do this so they can properly process special tag IDs */ 

/* like TAGSKIP, TAGIGNORE, etc. */ 

switch (ti->ti_Tag) 

{ 

case RKMMODCurrVal : 

if ( (ti->ti_Data) > mmd- >val limit) ti->ti_Data = 

mmd - >val 1 imi t ; 
mmd- >currval = ti - >ti_Data ; 
NotifyCurrVal (cl, o, msg, mmd) ; 

retval = (APTR) 1L; /* Changing RKMMODCurrVal can cause a visual */ 

break; /* change to gadgets in the rkmmodel' s broadcast */ 

/* list. The rkmmodel has to tell the applica- */ 

/* tion by returning a value besides zero. */ 

case RKMMODUp: 

mmd->currval++; 

/* Make sure the current value is not greater than value limit . */ 
if ( (mmd->currval) > mmd->vallimit) mmd->currval = mmd->vallimit; 
NotifyCurrVal (cl, o, msg, mmd) ; 

retval = (APTR) 1L; /* Changing RKMMODUp can cause a visual */ 

break; /* change to gadgets in the rkmmodel' s broadcast */ 



/* list . The rkmmodel has to tell the applica 
/* tion by returning a value besides zero, 
case RKMMODDown: 
mmd->currval- - ; 

/* Make sure currval didn't go negative. */ 
if { (LONG) (mmd->currval) == -1L) 

mmd->currval = OL; 
NotifyCurrVal (cl, o, msg, mmd) ; 

retval = (APTR) 1L; /* Changing RKMMODDown can cause a vi 

break; /* change to gadgets in the rkmmodel ' s 

/* list. The rkmmodel has to tell the 

/* tion by returning a value besides z 



*/ 
*/ 



case RKMMODLimit : 
mmd - >val 1 imi t = 
break; 



ti->ti_Data; /* Set the limit. Note that 
/* not do bounds checking on 
/* current RKMModData. currval 



sual 


*/ 


broadcast 


*/ 


applica- 


*/ 


ero . 


*/ 


this does 


*/ 


the 


*/ 


value. 


*/ 



} 



} 
} 

break; 
case OMGET: /* The only attribute that is "gettable" in this */ 

mmd = INST_DATA(cl, o) ; /* class or its superclasses is RKMMODCurrVal . */ 

if {(((struct opGet *}msg) ->opg_AttrID) == RKMMODCurrVal) 

{ 

♦(((struct opGet *)msg) ->opg_Storage) = mmd->currval; 
retval = (Object *)TRUE; 

} 

else retval = (APTR) DoSuperMethodA (cl, o, msg) ; 
break; 
default : /* rkmmodelclass does not recognize the methodID, so let the superclass' s */ 
/* dispatcher take a look at it . */ 

retval = (APTR) DoSuperMethodA {cl, o, msg); 
break; 



return ( (ULONG) retval) ; 



) 



void NotifyCurrVal (Class *cl. Object *o, struct opUpdate *msg, struct RKMModData *mmd) 

{ 

struct Tagltem tt[2]; 



tt [0] .tiTag = RKMMODCurrVal; 
tt[0] . tiData = nund->currval; 
tt[l] .ti Tag = TAGDONE; 

/* 



/* make a tag list . 



DoSuperMethod (cl, o, 
OMNOTIFY, 
tt, 
msg->opu_GInf o. 



*/ 



If the RKMMODCurrVal changes, we want everyone to know about */ 
/* it . Theoretically, the class is supposed to send itself a */ 
/* OMNOTIFY message. Because this class lets its superclass */ 
/* handle the OMNOTIFY message, it skips the middleman and */ 
/* sends the OMNOTIFY directly to its superclass. */ 



} 



( (msg->MethodID 



OMUPDATE) ? (msg->opu_Flags) : OL) ) ; /* If this is an OM UPDATE */ 

/* method, make sure the part the OMUPDATE message adds to the */ 

/* OMSET message gets added. That lets the dispatcher handle */ 

/* OM UPDATE and OM SET in the same case. */ 



Below is a diagram showing how an application could use an rkmmodelclass object: 
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In this diagram, the application uses buttongclass Boopsi gadgets to send the rkmmodelclass the RKMMODJJp 
and RKMMODDown attribute pulses. 

The example takes advantage of an odd feature of buttongclass. When the user clicks on a buttongclass gadget, 
it sends an OMJJPDATE to its ICATARGET, even though no Boopsi attribute of buttongclass has changed. It 
does this because it's a convenient way to report button clicks. 

Boopsi - Object Oriented Intuition 315 

Whenever a gadget sends a notification, the list of attribute/value pairs in the OM_NOTIFY message always 
contains the gadget's GAJD. This is an easy way for the button to inform its target of its ID so the target knows 
which gadget sent the OM_UPDATE message. When a buttongclass sends a notification because of a button 
click, it only sends out an OMJJPDATE about its GAJD because none of its attributes changed. 

When the user clicks one of the buttons in the rkmmodelclass diagram, the button uses an ICA_MAP to map its 
GAJD to one of the "dummy" pulse attributes, RKMMODJJp and RKMMODDown. When the rkmmodel 
receives the OMJJPDATE message about RKMMODJJp or RKMMODJDown, it increments or decrements its 
internal value. 

There is one more important thing to note about rkmmodelclass. Looking at the rkmmodelclass Object diagram 
above, an rkmmodel's RKMMOD_CurrVal changes because it received an OMJJPDATE message from one of its 
gadgets. RKMMOD_CurrVal can also change if the application explicitly set RKMMOD_CurrVal using SetAttrs() 
or SetGadgetAttrs(). 

The primary difference between the OMJ3ET message that SetAttrsQ sends and the OM_SET message that 
SetGadgetAttrs() sends is that SetAttrs() passes a NULL in opSet.ops_Glnfo instead of a Gadgetlnfo pointer. 
This doesn't present a problem for the rkmmodel object, because it doesn't use the Gadgetlnfo structure. The 
problem is that when the rkmmodel notifies its targets, some of which are gadgets, they can't update their visual 
state because they need a Gadgetlnfo to render themselves. For this reason, the rkmmodelclass dispatcher 
returns a positive non-zero value when an attribute change occurs that could cause a change in the visual state of 
any objects in its broadcast list. An application that uses rkmmodelclass must test the return value when calling 
SetAttrs() on an rkmmodelclass object to tell if the attribute change requires a visual refresh of the gadgets (see 
the Intuition Autodocs for RefreshGadgets()). 

Boopsi Dispatchers Can Execute on Intuition's Context. Notice that the gadgets in the figure 
above send OMJJPDATE messages to the rkmmodel when the user manipulates them. 
Because Intuition handles the user input that triggers the OMJJPDATE messages, Intuition 
itself is sending the OMJJPDATE messages. This means the rkmmodelclass dispatcher 
must be able to run on Intuition's context, which puts some limitations on what the dispatcher 
is permitted to do: it can't use dos. library, it can't wait on application signals or message ports, 
and it can't call any Intuition functions which might wait on Intuition. 

Although rkmmodelclass serves as an example of a class, it leaves a little to be desired in a real-world 
implementation. To create the "prop-integer-up/down" super gadget from the diagram above, the application has 
to create, initialize, and link nine Boopsi objects, which is tedious, especially if the application needs several of 
these super gadgets. Ideally, all these functions would be rolled into some subclass of gadgetclass. If there were 
such a class, an application would only have to create one instance of this subclass to get such a gadget. When 
the subclass received an OMJMEW message, it would take care of creating, initializing, and linking all of the 
Boopsi objects that make up the whole super gadget. 

White Boxes - The Transparent Base Classes 

Boopsi gadgets and images were designed to be backwards compatible with the old Intuition Gadgets and 
Images, so as part of their instance data, both types of objects have the old Intuition structures built into them. 
When NewObject() creates a new gadget or image object, the pointer it returns points to the object's embedded 
Gadget or Image corresponding structure. Because Intuition can tell the difference between Boopsi images and 
gadgets and the original images and gadgets, applications can use Boopsi images and gadgets interchangeably 
with the older Intuition entities. 
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Although normally considered a "programming sin", in some cases it is legal for class dispatchers to directly 



manipulate some internal fields of certain Boopsi objects. For compatibility reasons, a Boopsi image or gadget 
object contains an actual Image or Gadget structure. These objects are instances of the Transparent Base 
Classes, imageclass and gadgetclass. 

To change an attribute of a Boopsi object, you normally invoke the set method, OM_SET. The Intuition functions 
SetAttrs() and SetGadgetAttrs() invoke this method. A Boopsi class is informed of any attribute change at that 
time, allowing it to react to this change. The reaction can include validating the changed attribute, changing other 
attributes to match, or informing other objects of the change. That is the inherent advantage of using function 
calls to change attributes. 

When using conventional images and gadgets, you generally modify the structure's fields directly. This operation 
is very fast. For conventional images and gadgets, there is no class that needs to know about the changes, so 
there is no problem. However, this is untrue of Boopsi images and gadgets. Although directly modifying the 
Boopsi object's internal structure would provide a performance increase over using the Boopsi OM_SET 
mechanism, altering a Boopsi object's internal structure directly will not give the class the opportunity to react to 
any structure changes. This violates the Boopsi concept, and therefore cannot be done in general. 

In order to provide a balance between the flexibility of function-access and the performance of direct-access, the 
transparent base classes imageclass and gadgetclass do not depend on being informed of changes to certain 
fields in the internal Image and Gadget structures. This means that it is OK for the dispatchers of direct 
subclasses of imageclass and gadgetclass to modify specific fields of Boopsi images or gadgets. Applications and 
indirect subclass dispatchers of imageclass or gadgetclass may not modify those fields, since their parent classes 
may depend on hearing about changes to these fields, which the SetAttrs() call (or a similar function) provides. 

For dispatchers of direct subclasses of imageclass, the following are the only fields of the Image structure that are 
alterable: 

LeftEdge Width ImageData 

TopEdge Height PlanePick 

PlaneOnOff 

For dispatchers of direct subclasses of gadgetclass, the following are the only fields of the Gadget structure that 
are alterable: 

LeftEdge Flags GadgetText 

TopEdge GadgetType Special Info 

Width GadgetRender Activation 

Height SelectRender 

Under no circumstances may an application or an indirect subclass modify one of these fields, even if the 
subclass knows the superclasses do not depend on notification for this field. This is the only way to preserve the 
possibility for future enhancements to that superclass. Note that these fields are not alterable while the gadget or 
image object is in use (for example, when it is attached to a window). 
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Boopsi Gadgets 

One of the major enhancements to Intuition for Release 2 is the implementation of customizable Boopsi gadgets. 
Boopsi gadgets are not limited by dependencies upon Intuition Image and Gadget structures. Unlike Release 1.3 
gadgets, which were handled exclusively by Intuition, Boopsi gadgets handle their own rendering and their own 
user input. 

Since Boopsi gadgets draw themselves, there is almost no restriction on what they can look like. A Boopsi gadget 
can use graphics. library RastPort drawing functions to draw vector-based imagery which the gadget can scale to 
any dimension. Instead of just a two-state Boolean gadget, a Boopsi gadget can have any number of states, each 
of which has its own imagery. If a programmer wanted to he could even make a Boopsi gadget that uses the 
animation system to render itself. 

Because Boopsi gadgets handle their own input, they see all the user's input, which the gadget is free to interpret. 
While the user has a Boopsi gadget selected, the gadget can track mouse moves, process mouse and keyboard 
key presses, or watch the timer events. 



The power of a Boopsi gadget is not limited to its ability to handle its own rendering and user input. Boopsi 
gadgets are also Boopsi objects so the gain all the benefits Boopsi provides. This means all Boopsi gadgets 
inherit the methods and attributes from their superclasses. Boopsi gadgets can use Boopsi images to take care of 
rendering their imagery. A Boopsi gadget could be a "composite" gadget that is composed of several Boopsi 
gadgets, images, and models. 

The Boopsi Gadget Methods 

Intuition drives a Boopsi gadget by sending it Boopsi messages. Intuition uses a series of five Boopsi methods: 

GM_RENDER This method tells the gadget to render itself. 

GMHITTEST This method asks a gadget whether it has been "hit" by a mouse click. 

GM_GOACTIVE This method asks a gadget if it wants to be the active gadget. 

GM_HANDLEINPUT This method passes a gadget an input event. 

GM_GOINACTIVE This method tells a gadget that it is no longer active. 

The formats of each of these Boopsi messages differ, but they all have two things in common. Like all Boopsi 
messages, each starts with their respective method ID. For each of these methods, the method ID field is 
followed by a pointer to a Gadgetlnfo structure (defined in <intuition/cghooks.h>). The Gadgetlnfo structure 
contains information about the display on which the gadget needs to render itself: 

struct Gadgetlnfo { 

struct Screen *gi_Screen; 

struct Window *gi_Window; /* null for screen gadgets */ 

struct Requester *gi_Requester ; /* null if not GTYP_REQGADGET */ 

/* rendering information: don't use these without cloning/locking. 

* Official way is to call ObtainGIRPort ( ) 
*/ 

struct RastPort *gi_RastPort ; 
struct Layer *gi_Layer; 

/* copy of dimensions of screen/window/gOO/req (/group) 

* that gadget resides in. Left/Top of this box is 

* offset from window mouse coordinates to gadget coordinates 

* screen gadgets: 0,0 (from screen coords) 

* window gadgets (no gOO) : 0,0 

* GTYP_GZZGADGETs (borderlayer) : 0,0 
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* GZZ innerlayer gadget: borderleft, bordertop 

* Requester gadgets: reqleft, reqtop 
*/ 

struct IBox gi_Domain; 

/* these are the pens for the window or screen */ 
struct { 

UBYTE DetailPen; 

UBYTE BlockPen; 
} gi_Pens ; 

/* the Detail and Block pens in gi_DrInf o->dri_Pens [] are 

* for the screen. Use the above for window-sensitive colors. 
*/ 

struct Drawlnfo *gi_DrInfo; 

/* reserved space: this structure is extensible 

* anyway, but using these saves some recompilation 
*/ 

ULONG gi_Reserved[6] ; 

}; 

All the fields in this structure are read only. 



Although this structure contains a pointer to the gadget's RastPort structure, applications should not use it for 
rendering. Instead, use the intuition. library function ObtainGIRPort() to obtain a copy of the Gadgetlnfo's 
RastPort. When the gadget is finished with this RastPort, it should call ReleaseGIRPortQ to relinquish the 
RastPort. 

GM_RENDER 

Every time Intuition feels it is necessary to redraw a Boopsi gadget, it sends a gadget a GM_RENDER message. 
The GM_RENDER message (defined in <intuition/gadgetclass.h>) tells a gadget to render itself: 

struct gpRender 

{ 

ULONG MethodID; /* GM_RENDER */ 

struct Gadget Info *gpr_GInf ob- 
struct RastPort *gpr_RPort; /* all ready for use */ 
LONG gpr_Redraw; /* might be a "highlight pass" */ 

}; 

Some events that cause Intuition to send a GM_RENDER are: an application passed the gadget to 
OpenWindowQ, the user moved or resized a gadget's window, or an application explicitly asked Intuition to 
refresh some gadgets. 

The GM_RENDER message contains a pointer to the gadget's RastPort so the GM_RENDER method does not 
have to extract it from the gpr_Glnfo Gadgetlnfo structure using ObtainGIRPort(). The gadget renders itself 
according to how much imagery it needs to replace. The gpr_Redraw field contains one of three values: 

GREDRAW_REDRAW Redraw the entire gadget. 

GREDRAW_UPDATE The user has manipulated the gadget, causing a change to its imagery. Update only 
that part of the gadget's imagery that is effected by the user manipulating the gadget 
(for example, the knob and scrolling field of the prop gadget). 

GREDRAW_TOGGLE If this gadget supports it, toggle to or from the highlighting imagery. 
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Intuition is not the only entity that calls this method. The gadget's other methods may call this method to render 
the gadget when it goes through state changes. For example, as a prop gadget is following the mouse from the 
gadget's GMJHANDLEINPUT method, the gadget could send itself GM_RENDER messages, telling itself to 
update its imagery according to where the mouse has moved. 

GM_HITTEST 

When Intuition gets a left mouse button click in a window, one of the things it does is check through the window's 
list of gadgets to see if that click was inside the bounds of a gadget's Gadget structure (using the LeftEdge, 
TopEdge, Width, and Height fields). If it was (and that gadget is a Boopsi gadget), Intuition sends that gadget a 
GM_HITTEST message (defined in <intuition/gadgetclass.h>): 

struct gpHitTest 

{ 

ULONG MethodID; /* GM_HITTEST */ 

struct Gadgetlnfo *gpht_GInf o; 

struct 

{ 

WORD X; /* Is this point inside of the gadget? */ 
WORD Y; 



}; 



} gpht_Mouse ; 



This message contains the coordinates of the mouse click. These coordinates are relative to the upper-left of the 
gadget (LeftEdge, TopEdge). 

Because Intuition can only tell if the user clicked inside gadget's "bounding box", Intuition only knows that the click 
was close to the gadget. Intuition uses the GM_HITTEST to ask the gadget if the click was really inside the 
gadget. The gadget returns GMR_GADGETHIT (defined in <intuition/gadgetclass>) to tell Intuition that the user 



hit it, otherwise it returns zero. This method allows a gadget to be any shape or pattern, rather than just 
rectangular. 

GM_GOACTIVE/GM_HANDLEINPUT 

If a gadget returns GMR_GADGETHIT, Intuition will send it a GM_GOACTIVE message (defined in 
< intuition/gadgetclass. h>) : 

struct gplnput /* Used by GM_GOACTIVE and GM_HANDLEINPUT */ 

{ 

ULONG MethodID; 

struct Gadgetlnfo *gpi_GInfo; 
struct InputEvent *gpi_IEvent; 

/* The input event that triggered this method 
* (for GM_GOACTIVE, this can be NULL) */ 
LONG *gpi_Termination; 

/* For GADGETUP IntuiMessage . Code */ 

struct 

{ 

WORD X; /* Mouse position relative to upper */ 

WORD Y; /* left corner of gadget (Lef tEdge, TopEdge) */ 

} gpi_Mouse; 

}; 

The GM_GOACTIVE message gives a gadget the opportunity to become the active gadget. The active gadget is 
the gadget that is currently receiving user input. Under normal conditions, only one gadget can be the active 
gadget (it is possible to have more than one active gadget using a groupgclass object-See the Boopsi Class 
Reference in the Appendix B of this manual for more details). 
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While a gadget is active, Intuition sends it GMJHANDLEINPUT messages. Each GMJHANDLEINPUT message 
corresponds to a single InputEvent structure. These InputEvents can be keyboard presses, timer events, mouse 
moves, or mouse button presses. The message's gpiJEvent field points to this InputEvent structure. It's up to 
the GMJHANDLEINPUT method to interpret the meaning of these events and update the visual state of the 
gadget as the user manipulates the gadget. For example, the GMJHANDLEINPUT method of a prop gadget has 
to track mouse events to see where the user has moved the prop gadget's knob and update the gadget's imagery 
to reflect the new position of the knob. 

For the GMGOACTIVE method, the gpiJEvent field points to the struct InputEvent that triggered the 
GM_GOACTIVE message. Unlike the GMJHANDLEINPUT message, GM_GOACTIVE's gpiJEvent can be 
NULL. If the GM_GOACTIVE message was triggered by a function like intuition. library's ActivateGadget() and 
not by a real InputEvent (like the user clicking the gadget), the gpiJEvent field will be NULL. 

For gadgets that only want to become active as a direct result of a mouse click, this difference is important. For 
example, the prop gadget becomes active only when the user clicks on its knob. Because the only way the user 
can control the prop gadget is via the mouse, it does not make sense for anything but the mouse to activate the 
gadget. On the other hand, a string gadget doesn't care how it is activated because, as soon as it's active, it gets 
user input from the keyboard rather than the mouse. Not all gadgets can become active. Some gadgets cannot 
become active because they have been temporarily disabled (their Gadget.Flags GFLGJDISABLED bit is set). 
Other gadgets will not become active because they don't need to process input. For example, a toggle gadget 
won't become active because it only needs to process one input event, the mouse click that toggles the gadget 
(which it gets from the GM_GOACTIVE message). If a toggle gadget gets a GM_GOACTIVE message and its 
gpiJEvent field is not NULL, it will toggle its state and refuse to "go active". 

The GM_GOACTIVE method has to take care of any visual state changes to a gadget that a GM_GOACTIVE 
message might trigger. For example, the toggle gadget in the previous paragraph has to take care of toggling its 
visual state from selected imagery to unselected imagery. If the gadget goes through a state change when it 
becomes the active gadget, (like when a string gadget positions its cursor) GM_GOACTIVE has to take care of 
this. 

The return values of both GMJ30ACTIVE and GMJHANDLEINPUT tell Intuition whether or not the gadget wants 
to be active. A gadget's GMJ30ACTIVE method returns GMRJvlEACTIVE (defined in <intuition/gadgetclass.h>) 
if it wants to become the active gadget. A gadget's GMJHANDLEINPUT method returns GMRJvlEACTIVE if it 



wants to remain the active gadget. If a gadget either does not want to become or remain the active gadget, it 
returns one of the "go inactive" return values: 

GMR_NOREUSE Tells Intuition to throw away the gplnput.gpiJEvent InputEvent. 

GMR_REUSE Tells Intuition to process the gplnput.gpiJEvent InputEvent. 

GMR_NEXTACTIVE Tells Intuition to throw away the gplnput.gpiJEvent InputEvent and activate the next 

GFLGJTABCYCLE gadget. 
GMRJ 3 REVACTIVE Tells Intuition to throw away the gplnput.gpiJEvent InputEvent and activate the 

previous GFLGJTABCYCLE gadget. 

GMRJMOREUSE tells Intuition that the gadget does not want to be active and to throw away the InputEvent that 
triggered the message. For example, an active prop gadget returns GMRNOREUSE when the user lets go of 
the left mouse button (thus letting go of the prop gadget's knob). 
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For the GMJHANDLEINPUT method, a gadget can also return GMRJ=IEUSE, which tells Intuition to reuse the 
InputEvent. For example, if the user clicks outside the active string gadget, that string gadget returns 
GMRJ^EUSE. Intuition can now process that mouse click, which can be over another gadget. Another case 
where a string gadget returns GMRREUSE is when the user pushes the right mouse button (the menu button). 
The string gadget becomes inactive and the menu button InputEvent gets reused. Intuition sees this event and 
tries to pop up the menu bar. 

For the GMJ30ACTIVE method, a gadget must not return GMR_REUSE. If a gadget gets a GM_GOACTIVE 
message from Intuition and the message has an gpiJEvent, the message was triggered by the user clicking on 
the gadget. In this case, Intuition knows that the user is trying to select the gadget. Intuition doesn't know if the 
gadget can be activated, but if it can be activated, the event that triggered the activation has just taken place. If 
the gadget cannot become active for any reason, it must not let Intuition reuse that InputEvent as the gadget has 
already taken care of the the event's purpose (clicking on the gadget). In essence, the user tried to activate the 
gadget and the gadget refused to become active. 

The other two possible return values, GMRJMEXTACTIVE and GMRJ D REVACTIVE were added to the OS for 
Release 2.04. These tell Intuition that a gadget does not want to be active and that the InputEvent should be 
discarded. Intuition then looks for the next (GMRJMEXTACTIVE) or previous (GMRJDREVACTIVE) gadget that 
has its GFLGJTABCYCLE flag set in its Gadget.Activation field (see the gadgetclass attribute in the Boopsi 
Class Reference in the Appendix B of this manual). 

For both GMJ30ACTIVE and GMJHANDLEINPUT, the gadget can bitwise-OR any of these "go inactive" return 
values with GMRJ/ERIFY. The GMRJ/ERIFY flag tells Intuition to send a GADGETUP IntuiMessage to the 
gadget's window. If the gadget uses GMRJ/ERIFY, it has to supply a value for the IntuiMessage.Code field. It 
does this by passing a value in the gplnput.gpiJTermination field. This field points to a long word, the lower 
1 6-bits of which Intuition copies into the Code field. The upper 1 6-bits are for future enhancements, so clear 
these bits. 

GM_GOINACTIVE 

After an active gadget deactivates, Intuition sends it a GMGOINACTIVE message (defined in 
< intuition/gadgetclass. h>) : 

struct gpGoInactive 

{ 

ULONG MethodID; /* GM_GOINACTIVE */ 

struct Gadget Info *gpgi_GInf o; 

/* V37 field only! DO NOT attempt to read under V36! */ 

ULONG gpgi_Abort ; /* gpgi_Abort=l if gadget was */ 

/* aborted by Intuition */ 

/* and if gadget went inactive */ 

/* at its own request. */ 

}; 

The gpgi_Abort field contains either a or 1 . If 0, the gadget became inactive on its own power (because the 
GMJ30ACTIVE or GMJHANDLEINPUT method returned something besides GMRJvlEACTIVE). If gpgi_Abort 
is 1 , Intuition aborted this active gadget. Some instances where Intuition aborts a gadget include: the user clicked 



in another window or screen, an application removed the active gadget with RemoveGList(), and an application 
called ActiveWindow() on a window other than the gadget's window. 

The Active Gadget 

While a gadget is active, Intuition sends it a GM_HANDLEINPUT message for every timer pulse, mouse move, 
mouse click, and key press that takes place. A timer event pulse arrives about every tenth of a second. Mouse 
move events can arrive at a much higher rate than the timer pulses. Without even considering the keyboard, a 
gadget can get a lot of GMJHANDLEINPUT messages in a short amount of time. Because the active gadget has 
to handle a large volume of GM_HANDLEINPUT messages, the overhead of this method should be kept to a 
minimum. 

Because the gadget will always receive a GM_GOACTIVE message before it is active and a GM_GOINACTIVE 
message after it is no longer active, the gadget can use these methods to allocate, initialize, and deallocate 
temporary resources it needs for the GM_HANDLEINPUT method. This can significantly reduce the overhead of 
GMJHANDLEINPUT because it eliminates the need to allocate, initialize, and deallocate resources for every 
GMJHANDLEINPUT message. 

Note that the RastPort from ObtainGIRPortQ is not cachable using this method. If the GMJHANDLEINPUT 
method needs to use a RastPort, it has to obtain and release the RastPort for every GMJHANDLEINPUT 
message using ObtainGIRPort() and ReleaseGIRPort(). 

RKMButtonclass. c 

The following example is a sample Boopsi gadget, RKMButClass.c. While the user has the RKMButton 
selected, the gadget sends an OMJJPDATE message to its ICAJTARGET for every timer event the button sees. 
The gadget sends notification about its RKMBUTJ^ulse attribute, which is the horizontal distance in screen pixels 
the mouse is from the center of the button. The gadget takes care of rendering all of its imagery (as opposed to 
using a Boopsi image to do it). The gadget's imagery is scalable to any dimensions and can be set (using 
SetGadgetAttrs()) while the gadget is in place. 

One possible use for such a gadget is as buttons for a prop gadget. If the user has the prop gadget's RKMButton 
selected, while the mouse is to the left of the button's center, the knob on the prop gadget moves left. While the 
mouse is to the right of the button's center, the knob on the prop gadget moves right. The speed at which the 
knob moves is proportional to the horizontal distance from the mouse to the active RKMButton. 

;/* RKMButClass.c - Example Boopsi gadget for RKRM: Libraries 

; Execute me to compile me with Lattice 5.10b 

LC -bl -dO -cfistq -v -y -J73 RKMButClass.c 

Blink FROM LIB: c . o, RKMButClass . o TO TestBut LIBRARY LIB: LC. lib, LIB: Amiga. lib 

quit 

*/ 

#include <exec/types.h> 
#include <intuition/intuition.h> 
#include <intuition/classes.h> 
#include <intuition/classusr .h> 
#include <intuition/imageclass . h> 
#include <intuition/gadgetclass . h> 
#include <intuition/cghooks.h> 
#include <intuition/icclass.h> 
#include <utility/tagitem.h> 
#include <utility/hooks.h> 
#include <clib/exec protos. h> 
#include <clib/intuition protos . h> 
#include <clib/graphics protos . h> 
#include <clib/utility protos. h> 
#include <clib/alib protos. h> 
#include <clib/alib stdio protos . h> 

#include <graphics/gfxmacros.h> 

#ifdef LATTICE 

int CXBRK(void) { return(O); } /* Disable Lattice CTRL/C handling */ 

int chkabort (void) { return (0); } 

#endif 

UBYTE *vers = "\0$VER: TestBut 37.1"; 



/**************** Class specifics ****************/ 
ttdefine RKMBUTPulse (TAGUSER + 1) 

struct ButlNST 

{ 

LONG midX, midY; /* Coordinates of middle of gadget */ 

}; 

/* ButlNST has one flag: */ 

#define ERASE ONLY 0x00000001 /* Tells rendering routine to */ 

/* only erase the gadget, not */ 

/* rerender a new one. This */ 

/* lets the gadget erase it- */ 

/* self before it rescales. */ 

/* The functions in this module */ 

Class *initRKMButGadClass (void) ; 

BOOL freeRKMButGadClass (Class *) ; 

ULONG dispatchRKMButGad (Class *, Object *, Msg) ; 

void NotifyPulse (Class *, Object *, ULONG, LONG, struct gplnput *) ; 

ULONG RenderRKMBut (Class *, struct Gadget *, struct gpRender *) ; 

void geta4 (void) ; 

void MainLoop (ULONG, ULONG); 

/************************************************************************ 

/* The main() function connects an RKMButClass object to a Boopsi integer gadget, which */ 

/* displays the RKMButClass gadget's RKMBUT Pulse value. The code scales and move the */ 

/* gadget while it is in place. */ 

/************************************************************************ 

struct Tagltem pulse2int[] = 

{ 

{RKMBUT Pulse, STRINGA LongVal}, 

{TAG END,} 
}> 

#define INTWIDTH 4 
#define INTHEIGHT 2 

struct Library *IntuitionBase, *UtilityBase, *GfxBase; 

struct Window *w; 

Class Tkmbutcl; 

struct Gadget *integer, *but; 

struct IntuiMessage *msg; 

void main (void) 

{ 

if (IntuitionBase = OpenLibrary ("intuition. library" , 37L) ) 

{ 

if (UtilityBase = OpenLibrary ("utility. library" , 37L)) 

{ 

if (GfxBase = OpenLibrary ("graphics. library" , 37L)) 

{ 

if (w = OpenWindowTags (NULL, 

WA Flags, WFLG DEPTHGADGET | WFLG DRAGBAR | 

WFLG CLOSEGADGET | WFLG SIZEGADGET, 
WA IDCMP , IDCMP CLOSEWINDOW, 
WA Width, 640, 

WA Height, 200, 

TAG END) ) 



{ 



WindowLimits(w, 450, 200, 640, 200); 

if (rkmbutcl = initRKMButGadClass () ) 

{ 

if (integer = (struct Gadget *) NewObject (NULL, 
"strgclass" , 
GA ID, 1L, 

GA Top, (w->BorderTop) + 5L, 



GA Left, (w->BorderLeft) + 5L, 

GA Width, INTWIDTH, 

GA Height, INTHEIGHT, 

STRINGA LongVal, OL, 

STRINGA MaxChars, 5L, 

TAG END) ) 

if (but = (struct Gadget *) NewObject (rkmbutcl, 
NULL, 

GA ID, 2L, 

GA Top, (w->BorderTop) + 5L, 
GA Left, integer- >LeftEdge + 

integer- >Width + 5L, 
GA Width, 40L, 
GA Height, INTHEIGHT, 
GA Previous, integer, 
ICA MAP, pulse2int, 
ICA TARGET, integer, 
TAG END) ) 



{ 



AddGList(w, integer, -1, -1, NULL); 
RefreshGList (integer, w, NULL, -1); 

SetWindowTitles (w, 

"<-- Click to resize gadget Height", 

NULL) ; 
MainLoop (TAG DONE, OL) ; 

SetWindowTitles (w, 

"<-- Click to resize gadget Width", 

NULL) ; 
MainLoop (GA Height, 100L) ; 

SetWindowTitles (w, 

"<-- Click to resize gadget Y position", 

NULL) ; 
MainLoop (GA Width, 100L) ; 

SetWindowTitles (w, 

"<-- Click to resize gadget X position", 

NULL) ; 
MainLoop (GA Top, but->TopEdge + 20); 

SetWindowTitles (w, 

"<-- Click to quit", NULL); 
MainLoop (GA Left, but->Lef tEdge + 20); 



RemoveGList (w, integer, -1) 
DisposeObject (but) ; 

} 

DisposeObject (integer) ; 

} 

freeRKMButGadClass (rkmbutcl) ; 

} 
CloseWindow(w) ; 

} 

CloseLibrary (Gf xBase) ; 

} 

CloseLibrary (UtilityBase) ; 

} 

CloseLibrary (IntuitionBase) ; 

} 
} 

void MainLoop (ULONG attr, ULONG value) 

{ 

ULONG done = FALSE; 

SetGadgetAttrs(but, w, NULL, attr, value, TAG DONE) ; 

while (done == FALSE) 
{ 



WaitPort ( (struct MsgPort *)w->UserPort) ; 
while (msg = (struct IntuiMessage *) 

GetMsg( (struct MsgPort *) w->UserPort) ) 

{ 

if (msg->Class == IDCMP CLOSEWINDOW) 

{ 

done = TRUE; 

} 

ReplyMsg (msg) ; 



} 

/** Make the class and set up the dispatcher' s hook **/ 
Class *initRKMButGadClass (void) 

{ 

Class *cl = NULL; 

extern ULONG HookEntryO; /* defined in amiga.lib */ 

if ( cl = MakeClass( NULL, 

"gadgetclass", NULL, 
sizeof ( struct ButlNST ) , 
)) 

{ 

/* initialize the cl Dispatcher Hook */ 

cl->cl Dispatcher. h Entry = HookEntry; 

cl->cl Dispatcher. h SubEntry = dispatchRKMButGad; 



return ( cl 



} 



/****************** Free the class ****************/ 
BOOL freeRKMButGadClass ( Class *cl ) 

{ 

return (FreeClass (cl) ) ; 
} 

/********** T he RKMBut class dispatcher *********/ 
ULONG dispatchRKMButGad (Class *cl. Object *o, Msg msg) 

{ 

struct ButlNST *inst; 
ULONG retval = FALSE; 
Object *object; 

/* SAS/C and Manx function to make sure register A4 

contains a pointer to global data */ 
geta4 () ; 

switch (msg->MethodID) 

{ 

case OM NEW: /* First, pass up to superclass */ 
if (object = (Object *) DoSuperMethodA(cl, o, msg)) 

{ 

struct Gadget *g = (struct Gadget *) object; 

/* Initial local instance data */ 
inst = INST DATA (cl, object); 

inst->midX = g->LeftEdge + ( (g->Width) / 2) ; 
inst->midY = g->TopEdge + ( (g->Height) / 2) ; 

retval = (ULONG) object; 

} 
break; 

case GM HITTEST: 

/* Since this is a rectangular gadget this */ 
/* method always returns GMR GADGETHIT. */ 



retval = GMR GADGETHIT; 
break; 
case GM GOACTIVE: 

inst = INST DATA (cl, o) ; 

/* Only become active if the GM GOACTIVE */ 
/* was triggered by direct user input. */ 
if (((struct gplnput *)msg) ->gpi IEvent) 

{ 

/* This gadget is now active, change */ 
/* visual state to selected and render. */ 
((struct Gadget *)o)->Flags |= GFLG SELECTED; 

RenderRKMBut (cl, (struct Gadget *)o, (struct gpRender *)msg); 
retval = GMR MEACTIVE; 

} 

else /* The GM GOACTIVE was not */ 

/* triggered by direct user input. */ 
retval = GMR NOREUSE; 
break; 
case GM RENDER: 

retval = RenderRKMBut (cl, (struct Gadget *)o, (struct gpRender *)msg); 
break; 
case GM HANDLEINPUT: /* While it is active, this gadget sends its superclass an */ 

/* OM NOTIFY pulse for every IECLASS TIMER event that goes by*/ 

/* (about one every 10th of a second) . Any object that is */ 

/* connected to this gadget will get A LOT of OM UPDATE messages. */ 

{ 

struct Gadget *g = (struct Gadget *)o; 
struct gplnput *gpi = (struct gplnput *)msg; 
struct InputEvent *ie = gpi->gpi IEvent; 

inst = INST DATA (cl, o) ; 

retval = GMR MEACTIVE; 

if (ie->ie Class == IECLASS RAWMOUSE) 

{ 

switch (ie->ie Code) 

{ 

case SELECTUP: /*The user let go of the gadget so return GMR NOREUSE*/ 
/* to deactivate and to tell Intuition not to reuse */ 
/* this Input Event as we have already processed it. */ 

/*If the user let go of the gadget while the mouse was*/ 
/•over it, mask GMR VERIFY into the return value so */ 
/♦Intuition will send a Release Verify (GADGETUP) . */ 
if ( ( (gpi->gpi Mouse) .X < g->LeftEdge) | 

( (gpi->gpi Mouse) .X > g->LeftEdge + g->Width) | 
( (gpi->gpi Mouse) .Y < g->TopEdge) | 
( (gpi->gpi Mouse) .Y > g->TopEdge + g->Height) ) 
retval = GMR NOREUSE | GMR VERIFY; 
else 

retval = GMR NOREUSE; 

/* Since the gadget is going inactive, send a final*/ 
/* notification to the ICA TARGET. */ 

NotifyPulse (cl , o, 0L, inst->midX, (struct gp Input *)msg); 
break; 
case MENUDOWN: /* The user hit the menu button. Go inactive and let */ 
/* Intuition reuse the menu button event so Intuition can */ 
/* pop up the menu bar. */ 

retval = GMR REUSE; 

/* Since the gadget is going inactive, send a final */ 
/* notification to the ICA TARGET. */ 

NotifyPulse (cl , o, 0L, inst->midX, (struct gp Input *)msg); 
break; 
default: 

retval = GMR MEACTIVE; 
} 

} 

else if (ie->ie Class == IECLASS TIMER) 



/* If the gadget gets a timer event, it sends an interim OM NOTIFY */ 
NotifyPulse(cl, o, OPUF INTERIM, inst->midX, gpi) ; /* to its 
superclass. */ 

} 
break; 

case GM GOINACTIVE: /* Intuition said to go inactive. Clear the GFLG SELECTED */ 

/* bit and render using unselected imagery. */ 

((struct Gadget *)o)->Flags &= -GFLG SELECTED; 

RenderRKMBut (cl, (struct Gadget *)o, (struct gpRender *)msg); 
break; 
case OM SET:/*Although this class doesn't have settable attributes, this gadget class*/ 
/* does have scaleable imagery, so it needs to find out when its size and/or */ 
/* position has changed so it can erase itself, THEN scale, and rerender. */ 
if ( FindTagItem(GA Width, ((struct opSet *)msg) ->ops AttrList) | 
FindTagItem(GA Height, ((struct opSet *)msg) ->ops AttrList) | 
FindTagI tern (GA Top, ((struct opSet *)msg) ->ops AttrList) | 
FindTagItem(GA Left, ((struct opSet *)msg) ->ops AttrList) ) 

{ 

struct RastPort *rp; 

struct Gadget *g = (struct Gadget *)o; 

WORD x , y , w , h ; 

x = g->LeftEdge; 
y = g->TopEdge; 
w = g->Width; 
h = g->Height; 

inst = INST DATA (cl, o) ; 

retval = DoSuperMethodA(cl, o, msg) ; 

/* Get pointer to RastPort for gadget. */ 
if (rp = ObtainGIRPort ( ((struct opSet *)msg) ->ops GInfo) ) 

{ 

UWORD *pens = ((struct opSet *) msg) ->ops GInfo- >giDrInfo->dri Pens; 

SetAPen (rp, pens [BACKGROUNDPEN] ) ; 

SetDrMd(rp, JAM1) ; /* Erase the old gadget. */ 

RectFill(rp, x, y, x+w, y+h) ; 

inst->midX = g->LeftEdge + ( (g->Width) / 2) ; /*Recalculate where the */ 
inst->midY = g->TopEdge + ( (g->Height) / 2);/*center of the gadget is. */ 

/* Rerender the gadget. */ 
DoMethod(o, GM RENDER, ((struct opSet *) msg) ->ops GInfo, rp, GREDRAW REDRAW) ; 
ReleaseGIRPort (rp) ; 
} 
} 
else 

retval = DoSuperMethodA(cl, o, msg); 
break; 
default: /* rkmmodelclass does not recognize the methodID, let the superclass's */ 
/* dispatcher take a look at it. */ 

retval = DoSuperMethodA(cl, o, msg); 
break; 

} 

return (retval) ; 

} 

/******** Build an OMNOTIFY message for RKMBUTPulse and send it to the superclass. *******/ 
void NotifyPulse (Class *cl. Object *o, ULONG flags, LONG mid, struct gplnput *gpi) 

{ 

struct Tagltem tt[3]; 

tt[0].ti Tag = RKMBUT Pulse; 

tt[0].ti Data = mid - ( (gpi- >gpi Mouse) .X + ((struct Gadget *) o) ->Lef tEdge) ; 

tt[l].ti Tag = GAID; 

tt[l].ti Data = ((struct Gadget *) o) ->GadgetID; 



} 



tt[2].ti Tag = TAG DONE; 

DoSuperMethod(cl, o, OM NOTIFY, tt, gpi->gpi GInfo, flags) 



/************************** Erase and rerender the gadget. ******************************/ 

ULONG RenderRKMBut (Class *cl, struct Gadget *g, struct gpRender *msg) 

{ 

struct ButlNST *inst = INST DATA(cl, (Object *)g); 

struct RastPort *rp; 

ULONG retval = TRUE; 

UWORD *pens = msg->gpr GInfo- >gi DrInfo->dri Pens; 

if (msg->MethodID == GM RENDER) /*If msg is truly a GM RENDER message (not a gplnput that*/ 

/* looks like a gpRender), use the rastport within it... */ 
rp = msg->gpr RPort; 
else /* ...Otherwise, get a rastport using ObtainGIRPort () . */ 



rp = ObtainGIRPort (msg- >gpr GInfo) 



if (rp) 
{ 



UWORD back, shine, shadow, w, h, x, y; 

if (g->Flags &. GFLG SELECTED) /*If the gadget is selected, reverse the meanings of the*/ 
{ /* pens. */ 

back = pens [FILLPEN] ; 

shine = pens [SHADOWPEN] ; 

shadow = pens [SHINEPEN] ; 

} 
else 

{ 

back = pens [BACKGROUNDPEN] ; 

shine = pens [SHINEPEN] ; 

shadow = pens [SHADOWPEN] ; 

} 

SetDrMd(rp, JAM1) ; 

SetAPen(rp, back); /* Erase the old gadget. */ 

RectFill(rp, g->LeftEdge, 

g->TopEdge, 

g->LeftEdge + g->Width, 

g->TopEdge + g->Height) ; 

SetAPen(rp, shadow); /* Draw shadow edge. */ 

Move(rp, g->LeftEdge + 1, g->TopEdge + g->Height) ; 

Draw(rp, g->LeftEdge + g->Width, g->TopEdge + g->Height) ; 

Draw(rp, g->LeftEdge + g->Width, g->TopEdge + 1); 

w = g->Width / 4; /* Draw Arrows - Sorry, no frills imagery */ 

h = g->Height / 2; 

x = g->LeftEdge + (w/2) ; 

y = g->TopEdge + (h/2) ; 

Move(rp, x, inst->midY) ; 

Draw(rp, x + w, y) ; 

Draw(rp, x + w, y + (g->Height) - h) ; 

Draw(rp, x, inst->midY) ; 

x = g->LeftEdge + (w/2) + g->Width / 2; 

Move(rp, x + w, inst->midY) ; 
Draw(rp, x, y) ; 

Draw(rp, x, y + (g->Height) - h) ; 
Draw(rp, x + w, inst->midY) ; 

SetAPen(rp, shine); /* Draw shine edge. */ 

Move(rp, g->LeftEdge, g->TopEdge + g->Height - 1); 
Draw(rp, g->LeftEdge, g->TopEdge) ; 
Draw(rp, g->LeftEdge + g->Width - 1, g->TopEdge) ; 



if (msg->MethodID != GM RENDER) /* If we allocated a rastport, give it back. 
ReleaseGIRPort (rp) ; 



else retval = FALSE; 
return (retval) ; 



Function Reference 



The following are brief descriptions of the Intuition and amiga.lib functions discussed in this chapter. See the 
"Amiga ROM Kernel Reference Manual: Includes and Autodocs" for details on each function call. All these 
functions require Release 2 or a later version of the Amiga operating system. 



Table 12-1: Intuition Library Boopsi Functions 


Function 


Description 


NewObjectA() 


Create a new Boopsi object (tag array form). 


NewObject() 


Create a new Boopsi object (varargs form). 


DisposeObject() 


Dispose of a Boopsi object. 


SetAttrs() 


Set one or more of a Boopsi object's attributes (tag array form). 


SetGadgetAttrs() 


Set one or more of a Boopsi object's attributes (varargs form). 


GetAttr() 


Obtain an attribute from a Boopsi object. 


MakeClass() 


Create a new private or public Boopsi class. 


FreeClass() 


Free a Boopsi class created by MakeClass(). 


AddClassO 


Add a public Boopsi class to Intuition's internal list of public classes. 


RemoveClassO 


Remove a public Boopsi class that was added to Intuition's internal 




list with AddClass(). 


I ObtainGIRPortQ — 


Set up a RastPort for use by a Boopsi gadgetdispatcher. ' 



ReleaseGIRPort() 



Free a RastPort set up by ReleaseGIRPortQ. 



Table 12-2: Amiga.lib Boopsi Functions 



Function 
DoMethodA() 
DoMethod() 
DoSuperMethodA() 

DoSuperMethod() 

CoerceMethodA() 

CoerceMethod() 

SetSu p e r At tr s() 



Description 

Send a Boopsi message to a Boopsi object (tag array form). 

Send a Boopsi message to a Boopsi object (varargs form). 

Send a Boopsi message to a Boopsi object as if the object was an 

instance of its class's superclass (tag array form). 

Send a Boopsi message to a Boopsi object as if the object was an 

instance of its class's superclass (varargs form). 

Send a Boopsi message to a Boopsi object as if the object was an 

instance of the specified class (tag array form). 

Send a Boopsi message to a Boopsi object as if the object was an 

instance of the specified class (varargs form). 

Send a Boops i OM_SET message to the Boops i object's superc l ass. 



Chapter 13 
PREFERENCES 



To make the Amiga operating system easily configurable by the user, the OS comes with a family of editors and 
associated data files known collectively as Preferences. Preferences allows the user to set system-wide 
configuration options such as the printer driver to use, serial port baud rate and other items. To make an 
application appealing to the user, the system-wide Preferences settings should be respected as much as possible 
by applications. This chapter describes how to use the Preferences system in your programs. 

In Release 2 the number of Preference items and the way they are handled is very different from 1 .3 and earlier 
versions, though there is backward compatibility with old Preferences items. This chapter describes both the old 
1 .3 and the new Release 2 Preferences. 

Preferences in 1.3 and Older Versions of the OS 

In 1 .3, the Preferences program allows the user to see and change many system wide parameters, like the 
Workbench colors, pointer image, printer settings etc. When a Preferences item is changed, the new setting can 
be used temporarily (until a reset occurs) or stored permanently in the devs:system-configuration file. Under 1 .3, 
all Preferences items are stored in this file which the system reads at boot time to find out how to set various 
system-wide options. 

The 1.3 Preferences system allows the user to change the following items: 

Date and time of day. These are automatically saved in the battery-backed clock, if one is present. 

Key repeat speed - the speed at which a key repeats when held down. 

Key repeat delay - the amount of delay before a key begins repeating. 

Mouse speed - how fast the pointer moves when the user moves the mouse. 

Double-click delay - maximum time allowed between the two clicks of a mouse double click. For 
information about how to test for double-click timeout, see the description of the DoubleClick() function 
in the Amiga ROM Kernel Reference Manual: Includes and Autodocs. 

Preferences 331 

Text size - size of the default font characters. The user can choose 64-column mode (64 characters on a 
line in high-resolution and 32 characters in low-resolution mode) or 80 column mode (80 characters on a 
line in high-resolution and 40 characters in low-resolution mode). The first variable in the Preferences 
structure is FontHeight, which is the height of the characters in display lines. If this is equal to the 
constant TOPAZ_EIGHTY, the user has chosen the 80-column mode. If it is equal to TOPAZ_SIXTY, 
the user has chosen the 64-column mode. Note that certain utility programs allow the user to change the 
default font under 1 .3, so you cannot rely on the default font being Topaz 8 or 9. 

Display centering - allows the user to center the image on the video display. 

Serial port - the user can change the baud rate and other serial port parameters to accommodate 
whatever device is attached to the serial connector. Normally you use these values as defaults when 
you open the serial device. If you change the baud rate or other serial port options locally, it is good 
practice to reset them to the values specified in Preferences before quitting. 

Workbench colors - the user can change any of the four colors in the 1 .3 Workbench screen by adjusting 
the amounts of red, green and blue in each color. 

Printer - the user can select from a number of printers supported by the Amiga and also indicate whether 
the printer is connected to the serial connector or the parallel connector. 

Print characteristics - the user can select paper size, right and left margin, continuous feed or single 
sheets, draft or letter quality, pitch and line spacing. For graphic printing, the user can specify the 
density, scaling method, select a vertical or horizontal dump, etc. 



Reading 1.3 Preferences 

Applications can obtain a copy of Preferences by calling the Intuition function GetPrefs(). In a system in which 
there is no devs:system-configuration file, GetDefPrefs() can be used to obtain the Intuition default Preference 
settings. 

struct Preferences *GetPrefs (struct Preferences *pref erences, LONG size); 
struct Preferences *GetDefPrefs (struct Preferences *pref erences, LONG size); 

GetPrefs() and GetDefPrefsQ have two arguments, a pointer to a buffer to receive the copy of the user 
Preferences and the size of this buffer. The most commonly used data is grouped near the beginning of the 
Preferences structure and you are free to read only as much as you need. So, if you are only interested in the 
first part of the Preferences structure, you do not need to allocate a buffer large enough to hold the entire 
structure. These functions return a pointer to your buffer if successful, NULL otherwise. 

If you are using Intuition IDCMP for input, you can set the IDCMP flag IDCMP_NEWPREFS (formerly the 
NEWPREFS flag under V34 and earlier versions of the OS). With this flag set, your program will receive an 
IntuiMessage informing you changes have been made to Preferences. To get the latest settings, you would 
again call GetPrefs(). 
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Preferences Structure in 1 .3 

The Preferences structure in 1 .3 and earlier versions of the OS is a static 232 byte data structure defined in 
<intuition/preferences.h> as follows: 

struct Preferences 



/* the default font height */ 
BYTE FontHeight; 



/* height for system default font 



/* constant describing what's hooked up to the port */ 
UBYTE PrinterPort; 



/* the baud rate of the port */ 
UWORD BaudRate; 

/* various timing rates */ 
struct timeval KeyRptSpeed; 
struct timeval KeyRptDelay; 
struct timeval Doubleclick; 

/* Intuition Pointer data */ 
UWORD PointerMatrix[POINTERSIZE] 
BYTE XOffset; 
BYTE YOffset; 
UWORD color 17; 
UWORD colorl8; 
UWORD colorl9; 
UWORD PointerTicks; 

/* Workbench Screen colors */ 
UWORD colorO; 
UWORD colorl 
UWORD color2 
UWORD color3 



/* printer port connection 
/* baud rate for the serial port 



/* repeat speed for keyboard */ 
/* Delay before keys repeat */ 
/* Interval allowed between clicks */ 



/* Definition of pointer sprite */ 
/* X-Offset for active 'bit' */ 
/* Y-Offset for active 'bit' */ 
/***********************************/ 

/* Colours for sprite pointer */ 
/***********************************/ 

/* Sensitivity of the pointer */ 



/* Standard default colours */ 
/* Used in the Workbench */ 



/ 



*********************************** 



I 



I* positioning data for the Intuition View */ 

BYTE ViewXOffset; /* Offset for top lefthand corner */ 

BYTE ViewYOffset; /* X and Y dimensions */ 

WORD ViewInitX, ViewInitY; /* View initial offset values */ 



BOOL EnableCLI; 



/* CLI availability switch (OBSOLETE)*/ 



/* printer configurations */ 
UWORD PrinterType; /* printer type 

UBYTE PrinterFilename [FILENAME_SIZE] ; /* file for printer 



/* print format and quality configurations */ 



UWORD PrintPitch; 
UWORD PrintQuality; 
UWORD PrintSpacing; 
UWORD PrintLef tMargin; 
UWORD PrintRightMargin; 
UWORD Printlmage; 
UWORD PrintAspect ; 
UWORD PrintShade; 
WORD PrintThreshold; 

/* print paper descriptors */ 
UWORD PaperSize; 
UWORD PaperLength; 
UWORD Paper Type; 



/* print pitch */ 

/* print quality */ 

/* number of lines per inch */ 

/* left margin in characters */ 

/* right margin in characters */ 

/* positive or negative */ 

/* horizontal or vertical */ 

/* b&w, half-tone, or color */ 

/* darkness Ctrl for b/w dumps */ 



/* paper size */ 

/* paper length in number of lines */ 
/* continuous or single sheet */ 



/* Serial device settings: These are 6 nibble-fields in 3 bytes 
/* (these look a little strange so the defaults will map out to 0) 



UBYTE SerRWBits; 

UBYTE SerStopBuf ; 

UBYTE SerParShk; 

UBYTE LaceWB ; 



/* upper nibble 

/* lower nibble 

/* upper nibble 

/* lower nibble 

/* upper nibble 

/* lower nibble 
/* 



(8 -number of read bits) 
(8 -number of write bits) 
(number of stop bits - 1) 
(table value for BufSize) 
(value for Parity setting) 
(value for Handshake mode) 



if workbench is to be interlaced 



Preferences 333 



*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 



UBYTE WorkName [FILENAME_SIZE] ; /* temp file for printer 



BYTE 
BYTE 

UWORD 
UWORD 
UWORD 
UBYTE 
UBYTE 

UWORD 
UWORD 
UBYTE 



RowSizeChange ; 
ColumnSizeChange ; 



/* affect NormalDisplayRows/Columns */ 



PrintFlags; /* user preference flags */ 

PrintMaxWidth; /* max width of printed picture in lOths/in */ 
PrintMaxHeight ; /* max height of printed picture in lOths/in */ 
PrintDensity; /* print density */ 

PrintXOf f set ; /* offset of printed picture in lOths/inch */ 

wb_Width; /* override default workbench width */ 
wb_Height; /* override default workbench height */ 
wb_Depth; /* override default workbench depth */ 

ext_size; /* extension information -- do not touch! */ 

/* extension size in blocks of 64 bytes */ } ; 



Setting 1.3 Preferences 

The instance of the Preferences structure in memory can be changed with the Intuition SetPrefs() function: 

struct Preferences *SetPrefs (struct Preferences 'preferences, LONG size, BOOL inform); 

In addition to a buffer holding the Preferences structure, and the buffer size, this function takes an argument 
which indicates whether an IDCMP_NEWPREFS message should be broadcast to windows which have this flag 
set in the Window.lDCMPFIags field of their window. 

Avoid Using SetPrefsQ. This function is normally only used by Preferences-like utilities. There 
should be no need for a normal application to set the system Preferences with SetPrefs(). 

Alternatives to Setprefs 

Since the Amiga is a multitasking system, it is rarely correct for a single Amiga application to modify the user's 
system-wide Preferences. Instead, use methods such as the following to modify only your own application's 
appearance or behavior. 

Custom screen applications can control their own display mode, resolution, palette, and fonts. Use 
functions such a LoadRGB4() to change your own screen's palette, and SetFont() to change your own 
screen and window fonts. Workbench applications should never change the attributes of the user's 



Workbench. 

The mouse pointer for a window may be changed with SetPointer(). 

Serial device settings can be changed with the command SDCMD_SETPARAMS. 

Printer device settings may be changed by altering the printer's copy of the Preferences structure when 
you have the printer open. Note that Amiga applications should only keep the printer open while they 
are printing. This allows other applications to print, and also allows user changes to Printer Preferences 
to take effect. 

See the Inutition and graphics chapters of this manual, and the "Printer Device" and "Serial Device" chapters of 
the Amiga ROM Kernel Reference Manual: Devices for more information. 
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Preferences in Release 2 

Under Release 2 (V36), the way Preferences are handled is significantly different. No longer is there one 
Preferences program with one configuration file. Instead there can be any number of Preferences editors (there 
are currently 13), each with its own separate configuration file covering a specific area. All these Preferences 
editors have the same look and feel. Using separate Preferences editors and configuration files allows for adding 
new Preferences items (and editors) in future versions of the OS. 

Preferences Editors and Storage 

In Release 2, the devs:system-configuration file has been replaced by various .prefs files, located in the ENV:sys 
and ENVARC:sys directories. System Preferences options currently in use are located in ENV:sys. Permanent, 
saved copies of system Preferences files are stored in ENVARC:sys. The contents of ENVARC: is copied at boot 
time to ENV:. Applications may also store their own preference files in ENV: but should use a subdirectory for that 
purpose. 

Currently the following Preferences editors and files are available: 





Table 13-1 : Preferences Editors in Release 2 


Preferences Editor 


Preferences Configuration File 


IControl 


icontrol. prefs 


Input 


input.prefs 


Palette 


palette. ilbm 


Pointer 


pointer.ilbm 


Printer 


printer.prefs 


PrinterGfx 


printergfx. prefs 


Overscan 


overscan. prefs 


ScreenMode 


screenmode. prefs 


Serial 


serial. prefs 


— 


wbconfig. prefs 


Font 


wbfont.prefs, sysfont.prefs and screenfont.prefs 


Time 


... 


WBPattern 


wb.pat and win. pat 



Each .prefs file is managed by editor with the same name, except for wbconfig. prefs, which is written directly by 
Workbench and has no editor. One Preferences editor has no .prefs file, Time. That Preferences editor writes 
directly to the battery backed clock. 

When the user makes a change to a Preferences item with one of the editors, the changes will be saved in either 
ENV:sys or both ENV:sys and ENVARC:sys depending on whether the user saves the changes with the "Use" 
gadget or "Save" gadget of the Preferences editor. 

The "Use" gadget is for making temporary changes and the new preferences will be stored only in ENV:sys. If the 
user reboots, the old preferences will be restored from the permanent copy in ENVARC:sys. 

The "Save" gadget is for making permanent changes and the new preferences will be stored in both ENV:sys and 
ENVARC:sys. That way, if the user reboots, the new preferences will still be in effect since the system looks in 



ENVARC:sys to find out what preferences should be set to at boot time. 

Preferences 335 

The ENV: Directory and Notification 

One advantage of the new Preferences system in Release 2 is file notification. File notification is a form of 
interprocess communication available in Release 2 that allows an application to be automatically notified if a 
change is made to a specific file or directory. This makes it easy for the application to react to changes the user 
makes to Preferences files. 

File notification is also used by the system itself. The Release 2 Preferences control program, IPrefs, sets up 
notification on most of the Preferences files in ENV:sys. If the user alters a Preferences item (normally this is 
done with a Preferences editor), the system will notify IPrefs about the change and IPrefs will attempt to alter the 
user's environment to reflect the change. 

For example, if the user opens the ScreenMode Preferences editor and changes the Workbench screen mode to 
high-resolution, the new settings are saved in Screenmode.prefs in the ENV:sys directory. IPrefs sets up 
notification on this file at boot time, so the file system will notify IPrefs of the change. IPrefs will read in the 
Screenmode.prefs file and reset the Workbench screen to high resolution mode. 

Here's a short example showing how to set up notification on the serial. prefs file in ENV:sys. The program 
displays a message in a window whenever this file is changed (e.g., when the user selects the "Use" or "Save" 
gadget in the Serial Preferences editor). 

;/* prefnotify . c . - Execute me to compile me with SAS/C 5.10 

lc -cfistq -v -y - j 73 prefnotify. c 

blink from LIB : c .o,prefnotify .o to prefnotify lib LIB:LC.lib LIB :amiga. lib 

quit 

** prefnotify. c - notified if serial prefs change 
*/ 

#include <exec/types . h> 
#include <exec/memory . h> 
#include <dos/dos.h> 
#include <dos/notify . h> 

#include <stdio.h> 

#include <clib/exec_protos . h> 
#include <clib/dos_protos . h> 

#ifdef LATTICE 

int CXBRK(void) { return(O); } /* Disable Lattice CTRL/C handling */ 

int chkabort (void) { return(O); } /* really */ 

#endif 

#define PREFSFILENAME "ENV: sys/serial .prefs " 

static UBYTE *VersTag = "\0$VER: prefnot 37.1 (09.07.91)"; 

extern struct Library *DOSBase; 

void main (int argc, char **argv) 

{ 

BOOL done=FALSE; 

struct NotifyRequest *notifyrequest ; 

UBYTE * filename; 

LONG signum; 

ULONG signals; 

/* We need at least V37 for notification */ 
if (DOSBase->lib_Version >= 37) 

{ 

/* Allocate a NotifyRequest structure */ 

if (notifyrequest = AllocMem (sizeof (struct NotifyRequest), MEMF_CLEAR) ) 

{ 

/* And allocate a signalsbit */ 



if ( (signum = AllocSignal ( -1L) ) != -1) 

{ 

/* Initialize notification request */ 

filename = PREFSFILENAME; 

notifyrequest->nr_Name = filename; 

notifyrequest->nr_Flags = NRF_SEND_SIGNAL; 

/* Signal this task */ 

notifyrequest->nr_stuf f .nr_Signal .nr_Task = (struct Task *) FindTask (NULL) ; 

/* with this signals bit */ 

notifyrequest->nr_stuf f .nr_Signal .nr_SignalNum = signum; 

if ( (StartNotify (notifyrequest) ) == DOSTRUE) 

{ 

printf ( "Select Serial Prefs SAVE or USE to notify this program\n" ) ; 

printf ("CTRL-C to exit\n\n" ) ; 

/* Loop until Ctrl-C to exit */ 

while ( !done) 

{ 

signals = Wait ( (1L << signum) | SIGBREAKF_CTRL_C ); 

if (signals & (1L << signum)) 

printf ( "Notification signal received. \n" ) ; 
if (signals & SIGBREAKF_CTRL_C) 

{ 

EndNotify (notifyrequest) ; 
done=TRUE; 
} 
} 
} 
else printf ( "Can' t start notif ication\n" ) ; 
FreeSignal (signum) ; 

} 
else printf ("No signals available\n" ) ; 
FreeMem (notifyrequest , sizeof (struct NotifyRequest) ) ; 

} 

else printf ("Not enough memory for NotifyRequest . \n" ) ; 

} 

else printf ( "Requires at least V37 dos . library \n" ) ; 

} 

Preferences File Format in Release 2 

To understand the format of Preferences files, you must be familiar with IFF file standard (see the Amiga ROM 
Kernel Reference Manual: Devices for the complete specification). 

In general all Preferences files are stored in the IFF format with a type of PREF (see the exceptions noted below). 
Each file contains at least two Chunks, a header Chunk and a data Chunk. 

The Header Chunk 

The PRHD header chunk, contains a PrefHeader structure: 

struct PrefHeader 

{ 

UBYTE ph_Version; 
UBYTE ph_Type; 
ULONG ph_Flags; 

}; 

Currently all the fields are set to NULL. In future revisions these fields may be used to indicate a particular 
version and contents of a PREF chunk. 
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The Data Chunk 

The data Chunk that follows the header Chunk depends on the kind of Preferences data the file contains. The 
types of Preferences data Chunks that are currently part of the system are: 



Table 13-2: IFF Chunk Types in Release 2 Preferences Data Files 



Chunk Name 


Used With 


FONT 


Fonts, used for all font Preferences files. 




In future the PrefHeader may indicate what the 




font is used for. 


ICTL 


IControl 


INPT 


Input 


OSCN 


Overscan 


PGFX 


PrinterGfx 


PTXT 


PrinterText 


SCRM 


ScreenMode 


SERL 


Serial 



Each chunk contains a structure applicable to the type. 
FONT 



struct FontPrefs 



{ 



ICTL 



LONG 


fp 


Reserved [4 


UBYTE 


fp 


FrontPen; 


UBYTE 


fp 


BackPen; 


UBYTE 


fp 


DrawMode ; 



/* Textcolor */ 

/* Character background color */ 



struct TextAttr fp_TextAttr ; 

BYTE fp_Name [FONTNAMESIZE] ; /* Font name */ 



/* System reserved */ 

/* Verify timeout */ 

/* Meta drag mouse event */ 

/* IControl flags (see below) */ 

/* CKey: WB to front */ 

/* CKey: front screen to back */ 

/* CKey: Requester TRUE */ 

/* CKey: Requester FALSE */ 



struct IControlPref s 

{ 

LONG ic_Reserved [4] ; 
UWORD ic_TimeOut; 
WORD ic_MetaDrag; 
ULONG ic_Flags; 
UBYTE ic_WBtoFront; 
UBYTE ic_FrontToBack; 
UBYTE ic_ReqTrue; 
UBYTE ic_ReqFalse; 

}; 

The ic_Flags field can have the following values: 

ICF_COERCE_COLORS 

This indicates that a displaymode with a matching number of colors has preference over a correct 
aspect ration when screen coercing takes place. 

ICF_COERCE_LACE 

This indicates that chosing an interlaced display mode is allowed when coercing screens. Otherwise a 
non-interlaced display mode will be selected. 
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ICF_STRGAD_FILTER 

This indicates that control characters should be filtered out of string gadget user input. 

ICFJvlENUSNAP 

This indicates that an autoscroll screen should be snapped back to origin when the mouse 
menu-button is selected. 

Note that the command key values in the last four fields of the IControlPrefs structure are ANSI codes, not 
RAWKEY codes. 



INPT 



struct InputPrefs 

{ 

LONG 

UWORD 

struct timeval 



ip_Reserved [4] ; 
ip_PointerTicks ; 
ip_DoubleClick; 



struct timeval ip_KeyRptDelay 
struct timeval ip_KeyRptSpeed 
WORD ip_MouseAccel ; 



/* Sensitivity of the pointer */ 

/* Interval between clicks */ 

/* keyboard repeat delay */ 

/* Keyboard repeat speed */ 

/* Mouse acceleration */ 



OSCN 



struct OverscanPref s 



ULONG 
ULONG 
Point 
Point 



os_Reserved [4] 
os_DisplayID; 
os_ViewPos ; 
os Text; 



struct Rectangle os_Standard; 



/* Displaymode ID */ 

/* View X/Y Offset */ 

/* TEXT overscan dimension */ 

/* STANDARD overscan dimension */ 



PGFX 



struct PrinterGfxPref s 



}; 



LONG pg_Reserved [4] ; 
UWORD pg_Aspect; 
UWORD pg_Shade; 
UWORD pg_Image; 
WORD pg_Threshold; 
UBYTE pg_ColorCorrect ; 
UBYTE pg_D intensions; 
UBYTE pg_Dithering; 
UWORD pg_GraphicFlags; 
UBYTE pg_PrintDensity; 
UWORD pg_PrintMaxWidth; 
UWORD pg_PrintMaxHeight ; 
UBYTE pg_PrintXOffset; 
UBYTE pg_PrintYOf fset; 



/* Horizontal or vertical */ 

/* B&W, Greyscale, Color */ 

/* Positive or negative image */ 

/* Black threshold */ 

/* RGB color correction */ 

/* Dimension type */ 

/* Type of dithering */ 

/* Rastport dump flags */ 



/* Print density 1 - 
/* Maximum width */ 
/* Maximum height */ 



/* 
/* 



'/ 



X Offset 
Y Offset 



The possible values of each field are defined in <prefs/printergfx.h>. Note that your application is responsible for 
checking if the supplied values are valid. 
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PTXT 



struct PrinterTxtPref s 



LONG pt_Reserved[4] ; 

UBYTE pt_Driver [DRIVERNAMESIZE] 

UBYTE pt_Port; 



/* System reserved */ 

/* printer driver filename */ 
/* printer port connection */ 



UWORD pt_PaperType; 
UWORD pt_PaperSize; 
UWORD pt_PaperLength; 



/* Fanfold or single */ 

/* Standard, Legal, A4 , A3 etc. */ 

/* Paper length in # of lines */ 



UWORD pt_Pitch; 
UWORD pt_Spacing; 
UWORD pt_LeftMargin; 



/* Pica or Elite */ 
/* 6 or 8 LPI */ 
/* Left margin */ 



}; 
SCRM 



UWORD pt_RightMargin; 
UWORD pt_Quality; 



/* Right margin */ 
/* Draft or Letter */ 



struct ScreenModePref s 



ULONG sm_Reserved[4] 
ULONG smJDisplaylD; 
UWORD sm_Width; 
UWORD sm_Height; 
UWORD sm_Depth; 
UWORD sm Control; 



/* Displaymode ID */ 

/* Screen width */ 

/* Screen height */ 

/* Screen depth */ 

/* BIT 0, Autoscroll yes/no */ 



SERL 

struct SerialPrefs 

{ 

LONG sp_Reserved [4] ; 
ULONG sp_BaudRate ; 

ULONG sp_InputBuf fer; 
ULONG sp_OutputBuffer; 



/* System reserved 
/* Baud rate 



/* Input buffer: - 64K */ 

/* Future: Output: - 64K, def */ 



UBYTE sp_InputHandshake; /* Input handshaking 

UBYTE sp_OutputHandshake ; /* Future: Output handshaking 



}; 



UBYTE sp_Parity; 
UBYTE sp_BitsPerChar; 
UBYTE sp_StopBitS; 



/* Parity 

/* I/O bits per character 

/* Stop bits 



Other Preferences File Formats in Release 2 

Not every Preferences file is stored as an IFF file of type PREF. The palette. ilbm and pointer. ilbm files contain a 
regular ILBM FORM to store their imagery. The win. pat and wb.pat files use a raw format with 16 bytes reserved, 
followed by a WORD giving the total size of the pattern, a WORD giving the bitplane count, and byte arrays 
(currently 32 bytes) for each bitplane. The format of the wbconfig.prefs file is private. 
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Reading a Preferences File 

The following example shows a way to read a Preferences file. 



;/ 

LC 
Bl 
qu 

* * 

* * 

* * 

* * 
*/ 



showprefs.c - Execute me to compile me with SAS C 5.10 
bo -do -cfis -v -j73 showprefs.c 
ink FROM showprefs.o TO showprefs LIBRARY LIB : Amiga . lib 

it 

The following example shows a way to read a Preferences file. 

showprefs.c - parse and show some info from an IFF Preferences file 
NOTE: This example requires upcoming 2.1 prefs/ include files. 



IMPORTANT!! This example is not linked with startup code (eg. c. 
It uses strictly direct AmigaDOS stdio, and also demonstrates 
direct ReadArgs argument parsing. Therefore it is a CLI-only 
example. If launched from Workbench, packet errors would occur 
since the WbStartup message is still sitting in the process's 
pr_MsgPort , and the code would never be unloaded from memory. 



o) 



#include <exec/types .h> 
#include <dos/dos.h> 
#include <libraries/dos . h> 
#include <libraries/if fparse . h> 
#include <pref s/prefhdr . h> 
#include <pref s/f ont . h> 
#include <pref s/icontrol . h> 
#include <pref s/input . h> 
#include <pref s/overscan.h> 
#include <pref s/printergfx.h> 
#include <pref s/printertxt . h> 
#include <pref s/screenmode . h> 
#include <pref s/serial . h> 

#include <clib/exec_protos . h> 
#include <clib/dos_protos . h> 
#include <clib/if fparse_protos . h> 

struct ExecBase *SysBase; 
struct Library *DOSBase; 
struct Library *IFFParseBase; 

static UBYTE *IFFErrTxt[] = { 

"EOF", /* (end of file, not an error) */ 

"EOC", /* (end of context, not an error) */ 

"no lexical scope", 

"insufficient memory", 

"stream read error", 

"stream write error", 

"stream seek error", 

"file corrupt", 

"IFF syntax error", 

"not an IFF file", 

"required call-back hook missing", 

NULL, /* (return to client, never shown) */ 

}; 

LONG main (void) 

{ 

struct RDArgs *readargs = NULL; 

LONG rargs [2] ; 

struct IFFHandle * iff handle; 

struct ContextNode *cnode; 

struct StoredProperty *hdrsp; 

struct StoredProperty *sp; 

UBYTE * filename = NULL; 

LONG iff error, error =0, re = RETURN_OK; 

/* We must set up SysBase (we are not linked with startup code) */ 
SysBase = (*( (struct Library **) 4)); 

/* This no-startup-code example may not be used from Workbench */ 
if ((((struct Process *) FindTask (NULL) ) ->pr_CLI) ==NULL) 
return (RETURN_FAIL) ; 

if (DOSBase = OpenLibrary ( "dos . library" , 37)) { 

if (IFFParseBase = OpenLibrary ( "if fparse . library" , 37)) { 

readargs = ReadArgs ( "FILE/A" , rargs, NULL); 
if ( (readargs) && (rargs [0] ) ) { 

filename = (UBYTE *) rargs [0] ; 

/* allocate an IFF handle */ 
if (iff handle = AllocIFFO) { 

/* Open the file for reading */ 

if (iffhandle->if f_Stream = (LONG) Open (filename, MODEJDLDFILE) ) { 
/* initialize the iff handle */ 
InitlFFasDOS (iffhandle) ; 

if ((ifferror = OpenlFF (iffhandle, IFFF_READ) ) == 0) { 
PropChunk( iffhandle, ID_PREF, ID_PRHD) ; 



PropChunk( iff handle, ID_PREF, ID_FONT) 

PropChunk( iff handle, ID_PREF, ID_ICTL) 

PropChunk( iff handle, ID_PREF, ID_INPT) 

PropChunk( iff handle, ID_PREF, ID_OSCN) 

PropChunk( iff handle, ID_PREF, ID_PGFX) 

PropChunk( iff handle, ID_PREF, ID_PTXT) 

PropChunk( iff handle, ID_PREF, ID_SCRM) 

PropChunk( iff handle, ID_PREF, ID_SERL) 



for (;;) { 

ifferror = ParselFF (if f handle, IFFPARSE STEP) ; 



if (ifferror 
continue; 
else if (ifferror) 
break; 



IFFERR EOC) 



/* Do nothing is this is a PrefHeader chunk, 

* we'll pop it later when there is a pref 

* chunk . 

*/ 

if (cnode = CurrentChunk (if f handle) ) 

if (cnode->cn_ID == ID_PRHD | | cnode->cn_ID == ID_FORM) 
continue; 

/* Get the preferences header, stored previously */ 
hdrsp = FindProp ( iff handle, ID_PREF, ID_PRHD) ; 



if (sp = FindProp (iff handle, ID_PREF, ID_FONT) ) { 
Printf ( "FrontPen: %ld\n", 

(struct FontPrefs *) sp->sp_Data) ->fp_FrontPen) ; 
Printf ( "BackPen: %ld\n", 

(struct FontPrefs *) sp->sp_Data) ->fp_BackPen) ; 
Printf ( "DrawMode : %ld\n", 

(struct FontPrefs *) sp->sp_Data) ->fp_DrawMode) ; 
Printf ( "Font : %s\n", 

(LONG) ( (struct FontPrefs * ) sp->sp_Data) ->f p_Name) ; 
Printf ("ta_YSize: %ld\n", 

(struct FontPrefs *) sp->sp_Data) ->fp_TextAttr . ta_YSize) ; 
Printf ("ta_Style: %ld\n", 

(struct FontPrefs *) sp->sp_Data) ->fp_TextAttr . ta_Style) ; 
Printf ( "ta_Flags : %ld\n", 

(struct FontPrefs *) sp->sp_Data) ->fp_TextAttr . ta_Flags) ; 
} else if (sp = FindProp (if f handle, ID_PREF, ID_ICTL) ) { 
Printf ("TimeOut : %ld\n" , 

(struct IControlPref s *) sp->sp_Data) ->ic_TimeOut) ; 

"MetaDrag: %ld\n", 

(struct IControlPref s *) sp->sp_Data) ->ic_MetaDrag) ; 

"WBtoFront: %ld\n", 

(struct IControlPref s *) sp->sp_Data) ->ic_WBtoFront) ; 

"FrontToBack: %ld\n", 

(struct IControlPref s *) sp->sp_Data) ->ic_FrontToBack) ; 

"ReqTrue: %ld\n", 

(struct IControlPref s *) sp->sp_Data) ->ic_ReqTrue) ; 

"ReqFalse: %ld\n" , 

(struct IControlPref s *) sp->sp_Data) ->ic_ReqFalse) ; 



Printf 

Printf 

Printf 

Printf 

Printf 

/* etc 
else i 
Printf 

Printf 

Printf 



/* etc 



Printf 



/* etc 



Printf 



*/ 



} else if (sp = FindProp (if f handle, ID_PREF, ID_INPT) ) { 
"PointerTicks : %ld\n", 

(struct InputPrefs *) sp->sp_Data) ->ip_PointerTicks) ; 
"DoubleClick/Secs: %ld\n" , 

(struct InputPrefs *) sp->sp_Data) ->ip_DoubleClick. tvsecs) ; 
"DoubleClick/Micro: %ld\n" , 
(struct InputPrefs *) sp->sp_Data) ->ip_DoubleClick. tv_micro) ; 



*/ 



else if (sp = FindProp (if f handle, ID_PREF, ID_OSCN) ) { 



"DisplaylD: Ox%lx\n", 

(struct OverscanPref s *) sp->sp_Data) ->os_DisplayID) ; 

*/ 



} else if (sp = FindProp (if f handle, ID_PREF, ID_PGFX) ) { 



"Aspect: %ld\n", 

(struct PrinterGfxPref s *) sp->sp_Data) ->pg_Aspect) ; 



/* etc */ 
} else if (sp ■ FindProp (if f handle, ID_PREF, ID_PTXT) ) { 
Printf ( "Driver : %s\n", 

(LONG) ( (struct PrinterTxtPref s *) sp->sp_Data) ->pt_Driver) ; 
/* etc */ 
} else if (sp = FindProp (if f handle, ID_PREF, ID_SCRM) ) { 
Printf ( "DisplaylD: Ox%lx\n", 

((struct ScreenModePref s *) sp->sp_Data) ->sm_DisplayID) ; 
/* etc */ 
} else if (sp = FindProp (if f handle, ID_PREF, ID_SERL) ) { 
Printf ( "BaudRate: %ld\n", 

((struct SerialPrefs *) sp->sp_Data) ->sp_BaudRate) ; 
/* etc */ 
} 
} 

CloseIFF( iff handle) ; 
} 

if (iff error != IFFERR_EOF) { 

rargs [1] = (LONG) IFFErrTxt [-if f error - 1] ; 

VFPrintf (Output () , "%s: %s\n", rargs); 

re = RETURN_FAIL; 
} 

Close (if fhandle->iff_Stream) ; 
} else 

error = IoErr ( ) ; 

FreelFF (if f handle) ; 
} else { 

VFPrintf (Output () , "Can't allocate IFF handle\n", NULL); 
re = RETURN_FAIL; 

} 
} else 

error = IoErr ( ) ; 
CloseLibrary (IFFParseBase) ; 

SetloErr (error) ; 
if (error) { 

re = RETURN_FAIL; 

PrintFault (error, filename ? filename : " " ) ; 
} 
} 

if (readargs) FreeArgs (readargs) ; 
CloseLibrary (DOSBase) ; 

} else { 

re = RETURN_FAIL; 

Write (Output () , "Kickstart 2.0 required\n" , 23); 
} 

return (re) ; 
} 

Function Reference 

The following are brief descriptions of the system functions that relate to the use of Preferences. See the Amiga 
ROM Kernel Reference Manual: Includes and Autodocs for details on each function call. 



Table 13-3: Functions Used with Preferences 



Function 



GetPrets() 

SetPrefs() 
GetDefPrefs() 



Description 

uid i .3 (V34) tunction Tor maKing a copy ot tne preferences structure 
Old 1 .3 (V34) function for overwriting Preferences with new data 
Old 1 .3 (V34) function for copying default Preferences from ROM 



StartNotify() 

EndNotify() 

AlloclFFO 

InitlFFasDOSO 

OpenlFF() 

PropChunk() 

ParselFF() 

CurrentChunk() 

FindProp() 

CloselFF() 

FreelFF() 



Release 2 DOS library function for monitoring a .prefs file for changes 

Ends notification started with StartNotify() 

IFFParse library tunction that creates an IFFHandle for parsing 

Initialize the IFFHandle as a DOS stream 

Initialize an IFFHandle for reading or writing a new stream 

Specify a property chunk to store 

Parse an IFF file from the IFFHandle stream 

Returns the top level context of an IFF stream 

Search for a property chunk previously declared with PropChunk() 

Closes an IFF context opened with OpenlFF() 

Frees the IFFHandle created with AlloclFFQ 



Chapter 14 

WORKBENCH AND ICON 
LIBRARY 



Workbench is the graphic user interface to the Amiga file system that uses symbols called icons to represent 
disks, directories and files. This chapter shows how to use Workbench and its two support libraries 
workbench. library and icon. library. 

Workbench is both a system program and a screen. Normally it is the first thing the user sees when the machine 
is booted providing a friendly operating environment for launching applications and performing other important 
system activities like navigating through the Amiga's hierarchical filing system. 

All application programs should be compatible with Workbench. There are only two things you need to know to 
do this: how to make icons for your application, data files and directories; and how to get arguments if your 
application is launched from Workbench. 

The Info File 



The iconic representation of Amiga filing system objects is implemented through .info files. In general, for each 
file, disk or directory that is visible in the Workbench environment, there is an associated ./nfo file which contains 
the icon imagery and other information needed by Workbench. 

Icons are associated with a particular file or directory by name. For example, the icon for a file named myapp 
would be stored in a ./nfofile named myapp. info in the same directory. 

To make your application program accessible (and visible) in the Workbench environment, you need only supply a 
./nfofile with the appropriate name and type. The are four main types of icons (and .info files) used to represent 
Amiga filing system objects (Table (14-1). 
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Table 14-1 : Basic Workbench Icon Types 



Workbench 


Filing 


Result When 


Icon Type 


System Object 


Icon Is Activated 


Disk 


The root level directory 


Window opens showing files 
and subdirectories 


Drawer 


A subdirectory 


Window opens showing files 
and subdirectories 


Tool 


An executable file 
(i.e., an application) 


Application runs 


Project 


A data file 


Typically, the application 



that created the data file 
runs and the data file is 
automatically loaded into it. 

Icons can be created with the IconEdit program (in the Tools directory of the Extras disk), or by copying an 
existing .info file of the correct type. Icons can also be created under program control with PutDiskObjectQ. 
See the discussion of the icon library functions below for more on this. 

For an executable file the icon type must be set to tool. For a data file the icon type must be set to project. Create 
icons for your application disk and directories too. For a directory, the icon is stored in a .info file at the same 
level where the directory name appears (not in the directory itself). The icon type should be set to drawer. The 
icon for a disk should always be stored in a file named disk. info at the root level directory of the disk. The icon 
type should be set to disk. (The icon type can be set and the icon imagery edited with the IconEdit program.) 



Workbench Environment 

On the Amiga there are at least two ways to start a program running: 

By activating a tool or project icon in Workbench (an icon is activated by pointing to it with the mouse and 
double-clicking the mouse select button.) 

By typing the name of an executable file at the Shell (also known as the CLI or Command Line Interface) 

In the Workbench environment, a program is run as a separate process. A process is simply a task with 
additional information needed to use DOS library. 

By default, a Workbench program does not have a window to which its output will go. Therefore, stdin and stdout 
do not point to legal file handles. This means you cannot use stdio functions such as printfQ if your program is 
started from Workbench unless you first set up a stdio window. 

Some compilers have options or defaults to provide a stdio window for programs started from Workbench. In 
Release 2, applications can use an auto console window for stdio when started from Workbench by opening 
"CON:0/0/640/200/auto/close/wait" as a file. An auto console window will only open if stdio input or output occurs. 
This can also be handled in the startup code module that comes with your compiler. 
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Argument Passing In Workbench 

Applications started from Workbench receive arguments in the form of a WBStartup structure. This is similar to 
obtaining arguments from a command line interface through argc and argv. The WBStartup message contains 
an argument count and a pointer to a list of file and directory names. 

One Argument 

A program started by activating its tool icon gets one argument in the WBStartup message: the name of the tool 
itself. 

Two Arguments 

All project icons (data files) have a default tool field associated with them that tells Workbench which application 
tool to run in order to operate on the data that the icon represents. When the user activates a project icon, 
Workbench runs the application specified in the default tool field passing it two arguments in the WBStartup 
message: the name of the tool and the project icon that the user activated. 

Multiple Arguments 

With extended select, the user can activate many icons at once. (Extended select means the user holds down the 
Shift key while clicking the mouse select button once on each icon in a group, double-clicking on the last icon.) If 
one of the icons in a group activated with extended select is an application tool, Workbench runs that application 
passing it the name of all the other icons in the group. This allows the user to start an application with multiple 
project files as arguments. If none of the icons in a group activated with extended select is a tool icon, then 
Workbench looks in the default tool field of each icon in the order they were selected and runs the first tool it finds. 

WBStartup Message 

When Workbench loads and starts a program, its sends the program a WBStartup message containing the 
arguments as summarized above. Normally, the startup code supplied with your compiler will place a pointer to 
WBStartup in argv for you, set argc to zero and call your program. 

The WBStartup message, whose structure is outlined in <workbench/startup.h>, has the following structure 
elements: 

struct WBStartup 

{ 

struct Message sm_Message; /* a standard message structure */ 



struct 


MsgPort • 


k sm Process; 


/ 


BPTR 




sm Segment; 


/ 


LONG 




sm NumArgs ; 


/ 


char * 




sm ToolWindow; 


/ 


struct 


WBArg * 


sm ArgList; 


/ 



}; 



process descriptor for you */ 
a descriptor for your code */ 
number of elements in ArgList 
reserved for future use */ 
the arguments themselves */ 
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The fields of the WBStartup structure are used as follows. 

smMessage 

A standard Exec message. The reply port is set to the Workbench. 
sm_Process 

The process descriptor for the tool (as returned by CreateProc()) 
sm_Segment 

The loaded code for the tool (returned by LoadSegO) 
sm_NumArgs 

The number of arguments in sm_ArgList 
sm_Tool Window 

Reserved (not currently passed in startup message) 
sm_ArgList 

This is the argument list itself. It is a pointer to an array of WBArg structures with 

sm NumArgs elements. 

Workbench arguments are passed as an array of WBArg structures in the sm_ArgList field of WBStartup. The 
first WBArg in the list is always the tool itself. If multiple icons have been selected when a tool is activated, the 
selected icons are passed to the tool as additional WBArgs. If the tool was derived from a default tool, the project 
will be the second WBArg. If extended select was used, arguments other than the tool are passed in the order of 
selection; the first icon selected will be first (after the tool), and so on. 

Each argument is a struct WBArg and has two parts: wa_Name and wa_Lock. 



struct WBArg 

{ 

BPTR 




wa Lock; 


BYTE * 


wa Name ; 



/* a lock descriptor */ 

/* a string relative to that lock */ 

}; 

The wa_Name element is the name of an AmigaDOS filing system object. The wa_Name field of the first 
WBArg is always the name of your program and the wa_Lock field is an AmigaDOS Lock on the directory where 
your program is stored. 

If your program was started by activating a project icon, then you get a second WBarg with the wa_Name field 
containing the file name of the project and the wa_Lock containing an AmigaDOS Lock on the directory where 
the project file is stored. 

If your program was started through extended select, then you get one WBArg for each icon in the selected group 
in the order they were selected. The wa_Name field contains the file name corresponding to each icon unless the 
icon is for a directory, disk, or the Trashcan in which case the wa_Name is set to NULL. The wa_Lock field 
contains an AmigaDOS Lock on the directory where the file is stored. (For disk or drawer icons the wa_Lock is a 
lock on the directory represented by the icon. Or, wa_Lock may be NULL if the icon type does not support 
locks.) 
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Workbench Locks Belong to Workbench. You must never call UnLock() on a wa_Lock. 
These locks belong to Workbench, and Workbench will UnLock() them when the WBStartup 
message is replied by your startup code. You must also never UnLock() your program's initial 
current directory lock (i.e., the lock returned by an initial CurrentDir() call). The classic 
symptom caused by unlocking Workbench locks is a system hang after your program exits, 
even though the same program exits with no problems when started from the Shell. 

You should save the lock returned from an initial CurrentDirQ, and CurrentDirQ back to it 



before exiting. In the Workbench environment, depending on your startup code, the current 
directory will generally be set to one of the wa_Locks. By using CurrentDir(wa_Lock) and 
then referencing wa_Name, you can find, read, and modify the files that have been passed to 
your program as WBArgs. 

Example of Parsing Workbench Arguments 

The following example will display all WBArgs if started from Workbench, and all Shell arguments if started from 
the Shell. 

;/* prargs.c - Execute me to compile me with SAS C 5.10 
LC -bl -cfistq -v -y -j73 prargs.c 

Blink FROM LIB: c . cprargs . o LIB LIB: LC. lib, LIB: Amiga, lib TO prargs DEFINE main= tinymain 

quit 

** 

** The following example will display all WBArgs if started from 
** Workbench, and all Shell arguments if started from the Shell. 
** 

** NOTE: main and tinymain are prepended with two underscores. 
** 

** PrArgs.c - This program prints all Workbench or Shell (CLI) arguments. 

*/ 

#include <exec/types.h> 

#include <workbench/startup.h> 

#include <clib/dos protos.h> 

#include <clib/icon protos.h> 

#include <stdlib.h> 
#include <stdio.h> 

#ifdef LATTICE 

int CXBRK(void) { return(O); } /* Disable SAS Lattice CTRL/C handling */ 

int chkabort (void) { return(O); }/* really */ 

#endif 

void main (int argc, char **argv) 

{ 

struct WBStartup *argmsg; 
struct WBArg *wb arg; 
LONG ktr; 
BPTR olddir; 
FILE *outFile; 

/* argc is zero when run from the Workbench, 

** positive when run from the CLI. 

*/ 

if (argc == 0) 

{ 

/* AmigaDOS has a special facility that allows a window */ 
/* with a console and a file handle to be easily created. */ 
/* CON: windows allow you to use fprintf () with no hassle */ 
if (NULL != (outFile = f open ( "CON: 0/0/640/200/PrArgs" , "r+") ) ) 

{ 

/* in SAS/Lattice, argv is a pointer to the WBStartup message 

** when argc is zero. (run under the Workbench.) 

*/ 

argmsg = (struct WBStartup *)argv ; 

wb arg = argmsg- >sm ArgList ; /* head of the arg list */ 

fprintf (outFile, "Run from the workbench, %ld args.\n", 
argmsg- >sm NumArgs) ; 

for (ktr = 0; ktr < argmsg- >sm NumArgs; ktr++, wb arg++) 

{ 

if (NULL != wb arg- >wa Lock) 

{ 

/* locks supported, change to the proper directory */ 

olddir = CurrentDir (wb arg- >wa Lock) ; 

/* process the file. 

** If you have done the CurrentDir () above, then you can 



} 

else 
{ 



** access the file by its name. Otherwise, you have to 
** examine the lock to get a complete path to the file. 
*/ 

fprintf (outFile, "\tArg %2.21d (w/ lock): '%s'.\n", 
ktr, wb arg->wa Name) ; 

/* change back to the original directory when done. 

** be sure to change back before you exit. 

*/ 

CurrentDir (olddir) ; 

} 
else 

{ 

/* something that does not support locks */ 

fprintf (outFile, "\tArg %2.21d (no lock): '%s'.\n", 
ktr, wb arg->wa Name) ; 

} 
} 
/* wait before closing down */ 
Delay(500L) ; 
f close (outFile) ; 
} 



/* using 'tinymain' from lattice c. 

** define a place to send the output (originating CLI window = "*") 

** Note - if you open "*" and your program is RUN, the user will not 

** be able to close the CLI window until you close the "*" file. 

*/ 

if (NULL != (outFile = f open ( "*" , "r+") ) ) 

{ 

fprintf (outFile, "Run from the CLI, %d args.\n", argc) ; 

for ( ktr = 0; ktr < argc; ktr++) 

{ 

/* print an arg, and its number */ 

fprintf (outFile, "\tArg %2.21d: '%s'.\n", ktr, argv[ktr]); 

} 
f close (outFile) ; 

} 
} 
} 

The Icon Library 

The ./nfofile is the center of interaction between applications and Workbench. To help support the Workbench 
iconic interface and manage .info files, the Amiga operating system provides the icon library. The icon library 
allows you to create icons for data files and directories under program control and examine icons to obtain their 
Tool Types and other characteristics. 

Icon Library Data Structures 

The preceding sections discussed how icons are used to pass file name arguments to an application run from the 
Workbench. Workbench allows other types of arguments to be passed in the Tool Types array of an icon. To 
examine the Tool Types array or find other characteristics of the icon such as its type, applications need to read 
in the .info file for the icon. 
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The DiskObject Structure 

The actual data present in the .info file is organized as a DiskObject structure which is defined in the include file 
<workbench/workbench.h>. For a complete listing, see the Amiga ROM Kernel Reference Manual: Includes and 
Autodocs. The DiskObject structure contains the following elements: 

struct DiskObject 
{ 



UWORD 




do Magic; /* 


UWORD 




do Version; /* 


Struct 
UBYTE 


Gadget 


do_Gadget; /* 
do_Type ; 


char 




*do DefaultTool 


char 




**do ToolTypes; 


LONG 




do CurrentX; 


LONG 




do CurrentY; 


struct 


DrawerData 


*do DrawerData; 


char 




*do ToolWindow; 


LONG 




do StackSize; 



magic number at start of file */ 
so we can change structure */ 
a copy of in core gadget */ 



/* only applies to tools */ 
/* only applies to tools */ 

} ; 

do_Magic 

A magic number that the icon library looks for to make sure that the file it is reading really contains an 
icon. It should be the manifest constant WB_DISKMAGIC. PutDiskObject() will put this value in the 
structure, and GetDiskObjectQ will not believe that a file is really an icon unless this value is correct. 

do_Version 

This provides a way to enhance the .info file in an upwardly-compatible way. It should be 
WB_DISKVERSION. The icon library will set this value for you and will not believe weird values. 

do_Gadget 

This contains all the imagery for the icon. See the "Gadget Structure" section below for more details. 

do_Type 

The type of the icon; can be set to any of the following values. 
WBDISK The root of a disk 

WBDRAWER A directory on the disk 
WBTOOL An executable program 

WBPROJECT A data file 
WBGARBAGE The Trashcan directory 
WBKICK A Kickstart disk 

WBAPPICON Any object not directly associated with a filing system 
object, such as a print spooler (new in Release 2). 

Table 14-2: Workbench Object Types 

do_DefaultTool 

Default tools are used for project and disk icons. For projects (data files), the default tool is the 
program Workbench runs when the project is activated. Any valid AmigaDOS path may be entered in 
this field such as "SYS:myprogram", "dfO:mypaint", "myeditor" or ":work/mytool". 

For disk icons, the default tool is the diskcopy program ("SYS:System/DiskCopy") that will be used 
when this disk is the source of a copy. 
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do_ToolTypes 

This is an array of free-format strings. Workbench does not enforce any rules on these strings, but 
they are useful for passing environment information. See the section on "The Tool Types Array" below 
for more information. 

do_CurrentX, do_CurrentY 

Drawers have a virtual coordinate system. The user can scroll around in this system using the scroll 
gadgets on the window that opens when the drawer is activated. Each icon in the drawer has a 
position in the coordinate system. CurrentX and CurrentY contain the icon's current position in the 
drawer. Picking a position for a newly created icon can be tricky. NO_ICON_POSITION is a system 
constant for do_CurrentX and do_CurrentY that instructs Workbench to pick a reasonable place for the 
icon. Workbench will place the icon in an unused region of the drawer. If there is no space in the 
drawers window, the icon will be placed just to the right of the visible region. 

do_DrawerData 

If the icon is associated with a directory (WBDISK, WBDRAWER, WBGARBAGE), it needs a 
DrawerData structure to go with it. This structure contains an Intuition NewWindow structure (see the 
"Intuition Windows" chapter for more information): 



struct DrawerData 

{ 

struct NewWindow dd_NewWindow; /* structure to open window */ 

LONG dd_CurrentX ; /* current x coordinate of */ 

/* origin */ 

LONG dd_CurrentY ; /* current y coordinate of */ 

/* origin */ 

}; 

Workbench uses this to hold the current window position and size of the window so it will reopen in the 
same place. 

do_ToolWindow 

This field is reserved for future use. 

do_StackSize 

This is the size of the stack (in bytes) used for running the tool. If this is NULL, then Workbench will use 
a reasonable default stack size (currently 4K bytes). 

Stack Size is Taken from the Project Icon. When a tool is run via the default tool mechanism 
(i.e., a project was activated, not the tool itself), Workbench uses the stack size specified in 
the project's .info file and the tool's ./nfofile is ignored. 

The Gadget Structure 

To hold the icon's image, Workbench uses an Intuition Gadget structure, defined in <intuition/intuition.h>. 
Workbench restricts some of the values of the gadget. All unused fields should be set to or NULL. The 
Intuition gadget structure members that Workbench icons use are listed below. 

Gadget Names in Assembly Language Are Different. The assembly language version of the 
Gadget structure has leading "gg_" for each variable name. 

Width 

This is the width (in pixels) of the icon's active region. Any mouse button press within this range will be 
interpreted as having selected this icon. 
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Height 

This is the height (in pixels) of the icon's active region. Any mouse button press within this range will 
be interpreted as having selected this icon. 

Flags 

The gadget must be of type GADGIMAGE. Three highlight modes are supported: GADGHCOMP, 
GADGHIMAGE, and GADGBACKFILL. GADGHCOMP complements everything within the area defined 
by CurrentX, CurrentY, Width, Height. GADGHIMAGE uses an alternate selection image. 
GADGBACKFILL is similar to GADGHCOMP, but ensures that there is no "ring" around the selected 
image. It does this by first complementing the image, and then flooding all color 3 pixels that are on the 
border of the image to color 0. All other flag bits should be 0. 

Activation 

The activation should have only RELVERIFY and GADGIMMEDIATE set. 

Type 

The gadget type should be BOOLGADGET. 

GadgetRender 

Set this to an appropriate Image structure. 

SelectRender 

Set this to an appropriate alternate Image structure if and only if the highlight mode is GADGHIMAGE. 

The Image structure is typically the same size as the gadget, except that Height is often one pixel less than the 
gadget height. This allows a blank line between the icon image and the icon name. The image depth must be 2; 
PlanePick mustbe 3; and PlaneOnOff should be 0. The Nextlmage field should be null. 



struct 


DiskObject 


struct 


DiskObject 


BOOL 




void 
BOOL 




UBYTE 
BOOL 




struct 


DiskObject 


BOOL 





Icon Libraries Functions 

The icon library functions do all the work needed to read, write and examine an icon's ./nfofile and corresponding 
DiskObject structure: 

*GetDiskObject (UBYTE *name) ; 

*GetDiskObjectNew (UBYTE *name) ; (V36) 

PutDiskObject (UBYTE *name, struct DiskObject *diskobj); 

FreeDiskObject (struct DiskObject *diskobj); 

DeleteDiskObject (UBYTE *); (V37) 

*FindToolType (UBYTE **toolTypeArray, UBYTE *typeName) ; 
MatchToolValue (UBYTE *typeString, UBYTE *value) ; 

*GetDefDiskObjectNew(LONG type); (V36) 

PutDef DiskObject (struct DiskObject *diskobj); (V36) 
*BumpRe vis ion (UBYTE *newbuf, UBYTE *oldname) ; 

The icon library routine GetDiskObject() reads an icon's .info file from disk into a DiskObject structure it creates 
in memory where it can be examined or altered. PutDiskObject() writes the DiskObject out to disk and 
FreeDiskObjectQ frees the memory it used. If you modify any pointers in a DiskObject acquired via 
GetDiskObject(), replace the old pointers before calling FreeDiskObjectQ so that the proper memory will be 
freed. 
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Release 2 includes a new function named GetDiskObjectNewQ that works the same as GetDiskObject(), except 
that if no ./nfofile is found, a default DiskObject will be created for you. Also new for Release 2 is 
DeleteDiskObject() for removing .info files from disk, and the functions GetDefDiskObjectQ and 
PutDefDiskObject() which allow the default icons in ROM to be copied or replaced with new defaults in RAM. 

Once an icon's ./nfofile has been read into a DiskObject structure, the functions FindToolType() and 
MatchToolValue() can be used to examine the icon's Tool Types array. 

The Tool Types Array 

Earlier sections discussed how Workbench passes filenames as arguments to a program that's about to run. 
Workbench also allows other types of arguments to be passed in the Tool Types array of an icon. The Tool Types 
array is found in the do_ToolTypes field of the icon's DiskObject structure. 

In brief, Tool Types is an array of pointers to strings that contain any information an application wants to store 
such as the program options that were in effect when the icon was created. These strings can be used to encode 
information which will be available to all applications that read the icon's .info file. Users can enter and change a 
selected icon's Tool Types by choosing Information in the Workbench Icons menu. 

Workbench does not place many restrictions on the Tool Types array, but there are a few conventions you should 
follow. A string may be no more than 128 bytes long. The alphabet used is 8-bit ANSI (for example, normal 
ASCII with foreign-language extensions). This means that users may enter Tool Type strings containing 
international characters. Avoid special or nonprinting characters. The case of the characters is currently 
significant, so the string "Window" is not equal to "WINDOW". 

The general format for a Tool Types entry is <name>=<value>[|<value>], where <name> is the field name and 
<value> is the text to associate with that name. Multiple values for one name may be separated by a vertical bar. 
The values may be the type of the file, programs that can access the data, parameters to be passed to an 
application, etc. For example, a paint program might set: 

FILETYPE = PaintProgram | ILBM 

This Tool Type indicates that the file is an ILBM, perhaps with some additional chunks of data specific to 
PaintProgram. 

Tool Type strings have few restrictions but there are some reserved Tool Types that are parsed by Workbench 
itself when an application is started from an icon. The reserved Tool Types are TOOLPRI=n (sets the Exec task 
priority at which Workbench will start the application), STARTPRI=n (sets the starting order for icons in the 



Wbstartup drawer), and DONOTWAIT (tells Workbench not to wait for the return of a program started via an icon 
in the Wbstartup drawer). In addition to the reserved Tool Types, which applications should not use, there are 
standard Tool Types, which applications should use only in the standard way. For a list of standard Tool Types 
refer to the Amiga User Interface Style Guide. 

Two routines are provided to help you deal with the Tool Types array. FindToolType() returns the value of a Tool 
Type element. Using the above example, if you are looking for FILETYPE, the string "PaintProgram|ILBM" will be 
returned. MatchToolValueQ returns nonzero if the specified string is in the reference value string. This routine 
knows how to parse vertical bars. For example, using the reference value strings of "PaintProgram" or "ILBM", 
MatchToolValue() will return TRUE for "ILBM" and "PaintProgram" and FALSE for everything else. 

354 Amiga ROM Kernel Reference Manual: Libraries 

Example of Reading Icons and Parsing Tool Types 

The follwoing example demonstrates icon creation, icon reading and Tool Type parsing in the Workbench 
environment. When called from the Shell, the example creats a small data file in RAM: and creates or updates a 
project icon for the data file. The created project icon points to this example as its default tool. When the new 
project icon is double-clicked, Workbench will invoke the default tool (this example) as a Workbench process, and 
pass it a description of the project data file as a Workbench argument (WBArg) in WBStartup message. 

;/* iconexample . c - Execute me to compile me with SAS C 5.10 

LC -bl -cfistq -v -y -j73 iconexample . c 

Blink FROM LIB : c . o, iconexample . o TO iconexample LIBRARY LIB : LC . lib, LIB : Amiga . lib 

quit 

** The following example demonstrates icon creation, icon reading and 
** Tool Type parsing in the Workbench environment. When called from the 
** Shell, the example creates a small data file in RAM: and creates or 
** updates a project icon for the data file. The created project icon 
** points to this example as its default tool. When the new project 
** icon is double-clicked, Workbench will invoke the default tool (this 
** example) as a Workbench process, and pass it a description of the 
** project data file as a Workbench argument (WBArg) in the WBStartup 
** message. 
* * 

** iconexample . c - Workbench icon startup, creation, and parsing example 
*/ 

#include <exec/types . h> 
#include <libraries/dos . h> 
#include <workbench/workbench.h> 
#include <workbench/startup.h> 

#include <clib/alib_protos . h> 
#include <clib/exec_protos . h> 
#include <clib/dos_protos . h> 
#include <clib/icon_protos . h> 
#include <stdlib.h> 
#include <stdio.h> 
#include <string.h> 

#ifdef LATTICE 

int CXBRK(void) { return(O); } /* Disable SAS Lattice CTRL/C handling */ 

int chkabort (void) { return(O); }/* really */ 

#endif 

/* our functions */ 

void cleanexit (UBYTE *,LONG); 

void cleanup (void) ; 

void message (UBYTE *) ; 

BOOL make I con (UBYTE *, char **, char *); 

BOOL showToolTypes (struct WBArg *); 

UBYTE *projname = "RAM: Example_Project " ; 

UBYTE *conwinname = "CON: 10/10/620/180/iconexample" ; 

UBYTE def toolname [] = {"iconexample"}; 



USHORT Icon 
/* Plane 
0x0000, 
OxOFFF, 
0x0800, 
0x0800, 
0x0800, 
0x0800, 
0x0800, 
0x0800, 
0x0800, 
0x0000, 
0x0000, 
/* Plane 1 
OxFFFF, 
OxDOOO, 
0XD7FF, 
0XD7FF, 
0XD7FF, 
0XD7FF, 
0XD7FF, 
0XD7FF, 
0XD7FF, 
0xD555, 
0XD555, 



ImageDa 

*/ 

0x0000, 
OxFFFC, 
0x07FF, 
0x0400, 
0x042A, 
0x0400, 
0x0400, 
0x0400, 
0x042A, 
0x0400, 
0x0000, 

*/ 

OxFFFF, 
0x0001, 
0xF800, 
OxFBFF, 
0XFBD5, 
OxFBFF, 
OxFBFF, 
OxFBFF, 
0XFBD5, 
0X53FF, 
0x5555, 



tal[] = 

0x0000, 
0x0000, 
OxFFCO, 
0x0090, 
OxAOFC, 
0x0002, 
0x0002, 
0x0002, 
0x2AA2 , 
0x0002, 
0x0000, 

OxFFFF, 
0x5555, 
0x0015, 
0xFF65, 
0x5F01, 
OxFFFD, 
OxFFFD, 
OxFFFD, 
0XD55D, 
OxFFFD, 
0x5555, 



0x1000, 
0x3 000, 
0x3 000, 
0x3 000, 
0x3 000, 
0x3 000, 
0x3 000, 
0x3 000, 
0x3000, 
0x3000, 
0x3000, 

OxEOOO, 
0x4 000, 
0x4 000, 
0x4 000, 
0x4 000, 
0x4 000, 
0x4 000, 
0x4 000, 
0x4 000, 
0x4 000, 
0x4 000, 



0x0000, 
0x0800, 
0x08A8, 
0x08AA, 
0x082A, 
0x0800, 
0x0950, 
0x082A, 
OxOFFF, 
0x0000, 
Ox7FFF, 

OxD555, 
OxD7FF, 
0XD757, 
0XD755, 
0XD7D5, 
0XD7FF, 
0XD6AF, 
0XD7D5, 
OxDOOO, 
OxD555, 
0x8000, 



0x0000, 
0x0004, 
OxA400, 
OxA400, 
OxA400, 
0xA42A, 
0xA42A, 
OxA400, 
OxFCOO, 
Ox07FF, 
OxFFFF, 

0x5555, 
0xFFF9, 
0X5BFF, 
0X5BFF, 
0X5BFF, 
0X5BD5, 
0X5BD5, 
0X5BFF, 
0X03FF, 
0x5000, 
0x0000, 



0x0000, 
0x0000, 
0x0 OAO, 
0x0088, 
0x0002, 
0XA0A2, 
0x8AA2, 
0x0002, 
0x0002, 
OxFFFE, 
OxFFFF, 

0x5555, 
0x5555, 
OxFF55, 
OxFF75, 
OxFFFD, 
Ox5F5D, 
Ox755D, 
OxFFFD, 
OxFFFD, 
0x0001, 
0x0000, 



0x3 000, 
0x3 000, 
0x3000, 
0x3000, 
0x3000, 
0x3000, 
0x3 000, 
0x3 000, 
0x3 000, 
0x3 000, 
OxFOOO, 

0x4 000, 
0x4 000, 
0x4 000, 
0x4 000, 
0x4 000, 
0x4 000, 
0x4 000, 
0x4 000, 
0x4 000, 
0x4 000, 
0x0000, 



struct Image iconlmagel = 

{ 

0, 0, 

52, 22, 2, 

&IconImageDatal [0] 

0x003, 0x000, 

NULL 



}; 



/* Top Corner */ 



/* Width, Height, Depth */ 

/* Image Data */ 

/* PlanePick, PlaneOnOf f */ 

/* Next Image */ 



UBYTE *toolTypes[] 
{ 



"FILETYPE=text" , 

11 FLAGS = BOLD | ITALICS " 

NULL 

}; 



struct DiskObject projlcon = 

{ 

WB_DISKMAGIC, 
WB_D I S KVE RS I ON , 

{ 

NULL, 

97, 12,52,23, 
GADGIMAGE | GADGHBOX , 
GADGIMMEDIATE | RELVERIFY, 
BOOLGADGET , 
(APTR) &iconImagel, 
NULL, 
NULL, 
NULL, 
NULL, 
0, 
NULL 



/* Magic Number */ 

/* Version */ 

/* Embedded Gadget Structure */ 

/* Next Gadget Pointer */ 

/* Left, Top, Width, Height */ 

/* Flags */ 

/* Activation Flags */ 

/* Gadget Type */ 

/* Render Image */ 

/* Select Image */ 

/* Gadget Text */ 

/* Mutual Exclude */ 

/* Special Info */ 

/* Gadget ID */ 

/* User Data */ 



WBPROJECT, 

def toolname, 

toolTypes , 

NO_ICON_POSITION, 

NO_ICON_POSITION, 

NULL, 

NULL, 

4000 



/* Icon Type */ 

/* Default Tool */ 

/* Tool Type Array */ 

/* Current X */ 

/* Current Y */ 

/* Drawer Structure */ 

/* Tool Window */ 

/* Stack Size */ 



/* Opens and allocations we must clean up */ 



struct Library *IconBase = NULL; 
FILE *conwin = NULL; 
LONG olddir = -1; 

BOOL FromWb; 

void main(int argc, char **argv) 

{ 

struct WBStartup *WBenchMsg; 

struct WBArg *wbarg; 

FILE *file; 

LONG wLen ; 

SHORT i; 

FromWb = (argc==0) ? TRUE : FALSE; 

/* Open icon. library */ 

if ( ! (IconBase = OpenLibrary ( "icon. library" , 33) ) ) 

cleanexit ( "Can' t open icon. library\n" , RETURN_FAIL) ; 

/* If started from CLI, this example will create a small text 

* file RAM:Example_Project , and create an icon for the file 

* which points to this program as its default tool. 

*/ 

if ( ! FromWb) 

{ 

/* Make a sample project (data) file */ 

wLen = - 1 ; 

if ( f ile=f open (projname , "w" ) ) 

{ 

wLen = fprintf (file, "Have a nice day\n"); 

f close (file) ; 

} 
if (wLen < 0) cleanexit ( "Error writing data f ile\n" , RETURN_FAIL) ; 

/* Now save/update icon for this data file */ 
if (makelcon (projname, toolTypes, def toolname) ) 

{ 

printf("%s data file and icon saved. \n" , projname ) ; 

printf ("Use Workbench menu Icon Information to examine the icon.\n") 

printf("Then copy this example (iconexample) to RAM:\n"); 

printf ("and double-click the %s project icon\n" .projname) ; 

} 
else cleanexit ( "Error writing icon\n" , RETURN_FAIL) ; 



else /* Else we are FromWb - ie. we were either 

* started by a tool icon, or as in this case, 

* by being the default tool of a project icon. 
*/ 

{ 

if(!(conwin = f open (conwinname, "r+" ) ) ) 

cleanexit ( "Can' t open output window\n" , RETURN_FAIL) ; 

WBenchMsg = (struct WBStartup *)argv; 

/* Note wbarg++ at end of FOR statement steps through wbargs . 

* First arg is our executable (tool) . Any additional args 

* are projects/icons passed to us via either extend select 

* or default tool method. 

*/ 

for (i=0, wbarg=WBenchMsg->sm_ArgList ; 
i < WBenchMsg- >sm_NumArgs ; 
i++, wbarg++) 

{ 

/* if there's a directory lock for this wbarg, CD there */ 
olddir = -1; 

if ( (wbarg- >wa_Lock) && (* wbarg ->wa_Name) ) 
olddir = CurrentDir (wbarg- >wa_Lock) ; 

showToolTypes (wbarg) ; 



if ( (i>0) Sc& (*wbarg->wa_Name) ) 

fprintf (conwin, "In Main. We could open the %s file here\n", 
wbarg->wa_Name) ; 
if (olddir != -1) CurrentDir (olddir) ; /* CD back where we were */ 

} 
Delay (500) ; 

} 
cleanup ( ) ; 
exit (RETURNJDK) ; 
} 

BOOL makelcon (UBYTE 'name, char **newtooltypes, char *newdeftool) 

{ 

struct DiskObject *dobj ; 

char *olddef tool ; 

char **oldtooltypes ; 

BOOL success = FALSE; 

if (dobj=GetDiskObject (name) ) 

{ 

/* If file already has an icon, we will save off any fields we 

* need to update, update those fields, put the object, restore 

* the old field pointers and then free the object. This will 

* preserve any custom imagery the user has, and the user's 

* current placement of the icon. If your application does 

* not know where the user currently keeps your application, 

* you should not update his dobj ->do_Def aultTool . 

*/ 

oldtooltypes = dobj ->do_ToolTypes ; 
olddeftool = dobj ->do_Def aultTool; 

dobj ->do_ToolTypes = newtooltypes ; 
dobj ->do_Def aultTool = newdeftool; 

success = PutDiskObject (name, dobj ) ; 

/* we must restore the original pointers before freeing */ 
dobj ->do_ToolTypes = oldtooltypes; 
dobj ->do_Def aultTool = olddeftool; 
FreeDiskObject (dobj ) ; 

} 
/* Else, put our default icon */ 

if(lsuccess) success = PutDiskObject (name, &proj Icon) ; 
return (success) ; 



BOOL showToolTypes (struct WBArg *wbarg) 

{ 

struct DiskObject *dobj ; 

char ** toolarray; 

char *s; 

BOOL success = FALSE; 

fprintf (conwin, "\nWBArg Lock=0x%lx, Name=%s\n", 

wbarg->wa_Lock, wbarg->wa_Name) ; 

if ( (*wbarg->wa_Name) && (dobj=GetDiskObject (wbarg->wa_Name) ) ) 

{ 

fprintf (conwin, " We have read the DiskObject (icon) for this arg\n") 

toolarray = (char **) dobj ->do_ToolTypes ; 

if (s= (char *) FindToolType (toolarray, "FILETYPE") ) 

{ 

fprintf (conwin, " Found tooltype FILETYPE with value %s\n",s); 

} 
if (s= (char *) FindToolType (toolarray, "FLAGS") ) 

{ 

fprintf (conwin, " Found tooltype FLAGS with value %s\n",s); 

if (MatchToolValue (s, "BOLD") ) 

fprintf (conwin, " BOLD flag requested\n" ) ; 
if (MatchToolValue (s, "ITALICS") ) 

fprintf (conwin, " ITALICS flag requested\n" ) ; 



/* Free the diskobject we got */ 
FreeDiskObject (dobj ) ; 
success = TRUE; 

} 
else if ( ! (*wbarg->wa_Name) ) 

fprintf (conwin, " Must be a disk or drawer icon\n"); 
else 

fprintf (conwin, " Can't find any Diskobject (icon) for this WBArg\n"); 
return (success) ; 
} 

/* Workbench- started programs with no output window may want to display 
* messages in a different manner (requester, window title, etc) 

*/ 

void message (UBYTE *s) 

{ 

if(FromWb && conwin) fprintf (conwin, s, strlen (s) ) ; 

else if (IFromWb) printf(s); 

} 

void cleanexit (UBYTE *s, LONG n) 

{ 

if(*s) message (s); 

cleanup ( ) ; 

exit (n) ; 

} 

void cleanup () 

{ 

if (conwin) f close (conwin) ; 

if (IconBase) CloseLibrary (IconBase) ; 

} 

The Workbench Library 

Workbench arguments are sent to an application when it is started. There are also special facilities in Release 2 
of Workbench that allow an application that is already running to get additional arguments. These special facilities 
are known as AppWindow, Applcon and AppMenultem. 

An AppWindow is a special kind of window that allows the user to drag icons into it. Applications that set up an 
AppWindow will receive a message from Workbench whenever the user moves an icon into the AppWindow. 
The message contains the name of the file or directory that the icon represents. 

An Applcon is similar to an AppWindow. It is a special type of icon that allows the user to drag other icons on 
top of it. Like AppWindows, an application that sets up an Applcon will receive a message from Workbench 
whenever the user moves another icon on top of the Applcon. The message contains the name of the file or 
directory that the moved icon represents. 

An AppMenultem allows an application to add a custom menu item to the usual set of menu choices supported 
by Workbench. An application that sets up an AppMenultem will receive a message from Workbench whenever 
the user picks that item from the Workbench menus. 

When an application receives the messages described above, the message will include struct WBArg 
*am_ArgList containing the names (wa_Name) and directory locks (wa_Lock) of all selected icons that were 
passed as arguments by the user. This am_ArgList has the same format as the sm_ArgList of a WBStartup 
message. 

Workbench Library Functions 

AppWindows, Applcons and AppMenultems extend the user's ability to perform operations with the Workbench 
iconic interface. They all provide graphical methods for passing arguments to a running application. In order to 
manage AppWindows, Applcons and AppMenultems, the Amiga OS includes these Workbench library 
functions: 



struct Applcon *AddAppIconA ( ULONG, ULONG, char *, struct MsgPort *, struct FileLock *, 

struct DiskObject *, struct *TagItem ); 
struct AppMenuItem *AddAppMenuItemA ( ULONG, ULONG, char *, struct MsgPort *, 

struct *TagItem) ; 
struct AppWindow *AddAppWindowA ( ULONG, ULONG, struct Window *, struct MsgPort *, 

struct *TagItem) ; 

BOOL RemoveAppIcon (struct Applcon *); 

BOOL RemoveAppMenuItem (struct AppMenuItem *); 

BOOL RemoveAppWindow (struct AppWindow *); 

The functions AddAppMenultemA(), AddAppWindowA() and AddApplconA() have alternate entry points using 
the same function name without the trailing A. The alternate functions accept any Tagltem arguments on the 
stack instead of from an array. See the listings below for examples. 
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An Applcon Example 

The example listed here shows how to create a Applcon and obtain arguments from Workbench when then user 
drops other icons on top of it. The Applcon will appear as a disk icon named "TestApplcon" on the Workbench 
screen. (All Applcons appear on the Workbench screen or window) 

For convenience, this example code uses GetDefDiskObjectQ to create the icon imagery for the Applcon. 
Applications shoudl never do this. Use your own imagery for Applcons instead. 

/* The example listed here shows how to create an Applcon and obtain 

* arguments from Workbench when the user drops other icons on top of 

* it. The Applcon will appear as a disk icon named "TestApplcon" on the 

* Workbench screen. (All Applcons appear on the Workbench screen or 

* window. ) 

* For convenience, this example code uses GetDefDiskObject ( ) to create 

* the icon imagery for the Applcon. Applications should never do this. 

* Use your own custom imagery for Applcons instead. 
*/ 

/* appicon.c - Compiled under SAS C 5.10 with lc -L appicon.c */ 

/* Requires Kickstart version 37 or later. Works from the Shell (CLI) only */ 

#include <exec/types .h> /* Need this for the Amiga variable types */ 

#include <workbench/workbench.h> /* This has DiskObject and Applcon structs */ 

#include <workbench/startup.h> /* This has WBStartup and WBArg structs */ 

#include <exec/libraries .h> /* Need this to check library versions */ 

#include <clib/icon_protos .h> /* Icon (DiskObject) function prototypes */ 
#include <clib/exec_protos .h> /* Exec message, port and library functions*/ 
#include <clib/wb_protos .h> /* Applcon function protos */ 

#ifdef LATTICE 

int CXBRK(void) { return(O); } /* Disable SAS Lattice CTRL/C handling */ 

int chkabort (void) { return(O); }/* really */ 

#endif 

extern struct Library *SysBase; 
struct Library *IconBase; 
struct Library *WorkbenchBase; 

void main (int argc, char **argv) 

{ 

struct DiskObject *dobj=NULL; 
struct MsgPort *myport=NULL; 
struct Applcon *appicon=NULL; 
struct AppMessage *appmsg=NULL; 

LONG dropcount=0L; 

ULONG x; 

BOOL success=0L; 

/* Get the the right version of the Icon Library, initialize IconBase */ 



ifdconBase = OpenLibrary ( "icon, library" , 37) ) 

{ 

/* Get the the right version of the Workbench Library */ 

if (WorkbenchBase=OpenLibrary ( "workbench. library" , 37) ) 

{ 

/* This is the easy way to get some icon imagery */ 

/* Real applications should use custom imagery */ 

dobj=GetDefDiskObject (WBDISK) ; 

if (dobj !=0) 

{ 

/* The type must be set to NULL for a WBAPPICON */ 

dobj - >do_Type=NULL ; 

/* The CreateMsgPort ( ) function is in Exec version 37 and later only */ 
myport=CreateMsgPort ( ) ; 
if (myport) 

{ 

/* Put the Applcon up on the Workbench window */ 

appicon=AddAppIconA(OL, OL, "Test Applcon" , myport, NULL, dobj ,NULL) ; 
if (appicon) 

{ 

/* For the sake of this example, we allow the Applcon */ 
/* to be activated only five times. */ 

printf("Drop files on the Workbench AppIcon\n" ) ; 
printf ( "Example exits after 5 drops\n"); 

while (dropcount<5) 

{ 

/* Here's the main event loop where we wait for */ 
/* messages to show up from the Applcon */ 
WaitPort (myport) ; 

/* Might be more than one message at the port. . . */ 
while (appmsg= (struct AppMessage *) GetMsg (myport) ) 

{ 

if (appmsg->am_NumArgs==OL) 

{ 

/* If NumArgs is the Applcon was activated directly */ 

printf ("User activated the Applcon. \n" ) ; 

printf ("A Help window for the user would be good here\n") ; 

} 
else if (appmsg->am_NumArgs>OL) 

{ 

/* If NumArgs is >0 the Applcon was activated by */ 
/* having one or more icons dropped on top of it */ 
printf ("User dropped %ld icons on the AppIcon\n", 

appmsg->am_NumArgs) ; 
for (x=0 ;x<appmsg->am_NumArgs ;x++) 

{ 

printf ("#%ld name=' %s' \n" ,x+l , appmsg->am_ArgList [x] .wa_Name) 

} 
} 
/* Let Workbench know we're done with the message */ 
ReplyMsg ( (struct Message *)appmsg); 

} 

dropcount++; 

} 
success=RemoveAppIcon (appicon) ; 

} 
/* Clear away any messages that arrived at the last moment */ 
while (appmsg= (struct AppMessage *) GetMsg (myport) ) 

ReplyMsg ( (struct Message *)appmsg); 
DeleteMsgPort (myport) ; 

} 
FreeDiskObject (dobj ) ; 

} 
CloseLibrary (WorkbenchBase) ; 

} 
CloseLibrary (IconBase) ; 



An AppMenultem Example 

This example shows how to create an AppMenultem. This example adds a menu item named "Browse Files" to 
the Workbench Tools menu. (All AppMenultems appear in the Workbench Tools menu.) When the menu is 
activated. The example program recieves a message from Workbench and then attempts to start up an instance 
of the More program. (The More program is in the Utilities directory of your Workbench disk.) 

The example starts up the More program as a separate, asynchronous process using the new SystemTags() 
function of Release 2 AmigaDOS. For more about the SystemTags() function refer to the AmigaDOS Manual, 
3rd Edition from Bantam Books. When the AppMenultem has been activated five times, the program exits after 
freeing any system resources it has used. 

/* This example shows how to create an AppMenultem. The example adds a 

* menu item named "Browse Files" to the Workbench Tools menu. (All 

* AppMenultems appear in the Workbench Tools menu.) When the menu item 

* is activated, the example program receives a message from Workbench 

* and then attempts to start up an instance of the More program. (The 

* More program is in the Utilities directory of the Workbench disk.) 

* The example starts up the More program as a separate, asynchronous 

* process using the new SystemTagsO function of Release 2 AmigaDOS. 

* For more about the SystemTagsO function refer to the AmigaDOS 

* Manual, 3rd Edition from Bantam Books. When the AppMenultem has been 

* activated five times, the program exits after freeing any system 

* resources it has used. 
*/ 

/* appmenuitem. c - Compiled under SAS C 5.10 with lc -L appmenuitem. c */ 
/* Requires Kickstart version 37 or later. Works from the Shell (CLI) only */ 

#include <exec/types . h> /* Need this for the Amiga variable types */ 

#include <workbench/workbench.h> /* This has DiskObject and Applcon structs */ 

#include <workbench/startup.h> /* This has WBStartup and WBArg structs */ 

#include <exec/libraries . h> 

#include <dos/dostags . h> 

#include <stdio.h> 

#include <clib/dos_protos . h> 

#include <clib/exec_protos . h> /* Exec message, port and library functions*/ 

#include <clib/wb_protos . h> /* AppMenultem function protos */ 

#ifdef LATTICE 

int CXBRK(void) { return(O); } /* Disable Lattice CTRL/C handling */ 

int chkabort (void) { return(O); }/* really */ 

#endif 

extern struct Library *SysBase; 
struct Library *WorkbenchBase; 

void main (int argc, char **argv) 

{ 

struct MsgPort *myport=NULL 

struct AppMenultem *appitem=NULL 

struct AppMessage *appmsg=NULL 

LONG result, x, count = 0L; 

BOOL success=0L; 

BPTR file; 

if (WorkbenchBase = OpenLibrary ( "workbench. library" , 37) ) 

{ 

/* The CreateMsgPort ( ) function is in Exec version 37 and later only */ 

if (myport = CreateMsgPort () ) 

{ 

/* Add our own AppMenultem to the Workbench Tools Menu */ 
appitem=AddAppMenuItemA(OL, /* Our ID# for item */ 

(ULONG) "SYS:Utilities/More" , /* Our UserData */ 
"Browse Files", /* Menultem Text */ 
myport , NULL) ; /* MsgPort, no tags */ 

if (appitem) 
{ 



printf ( "Select Workbench Tools demo menuitem 'Browse Files'\n"); 

/* For this example, we allow the AppMenuItem to be selected */ 
/* only once, then we remove it and exit */ 

WaitPort (myport) ; 
while ( (appmsg= (struct AppMessage *) GetMsg (myport) ) && (count<l) ) 

{ 

/* Handle messages from the AppMenuItem - we have only one */ 

/* item so we don't have to check its appmsg->am_ID number. */ 

/* We'll System () the command string that we passed as */ 

/* userdata when we added the menu item. */ 

/* We find our userdata pointer in appmsg->am_UserData */ 

printf ("User picked AppMenuItem with %ld icons selected\n", 

appmsg->am_NumArgs) ; 
for (x=0 ;x<appmsg->am_NumArgs ;x++) 

printf (" #%ld name=' %s' \n" ,x+l , appmsg->am_ArgList [x] . wa_Name) ; 

count++; 

if ( f ile=Open ( "CON: 0/40/640/150/AppMenu Example/auto/close/wait" , 
MODEJDLDFILE) ) /* for any stdio output */ 

{ 

result=SystemTags ( (UBYTE *) appmsg->am_UserData, SYS_Input , f ile, 

SYSJDutput , NULL , 
SYS_Asynch, TRUE , 
TAG_DONE) ; 

/* If Asynch System () itself fails, we must close file */ 

if (result == -1) Close (file) ; 

} 
ReplyMsg ( (struct Message *)appmsg); 

} 

success=RemoveAppMenuItem (appitem) ; 

} 

/* Clear away any messages that arrived at the last moment */ 
/* and let Workbench know we're done with the messages */ 
while (appmsg= (struct AppMessage *) GetMsg (myport) ) 

{ 

ReplyMsg ( (struct Message *)appmsg); 

} 

DeleteMsgPort (myport) ; 

} 
CloseLibrary (WorkbenchBase) ; 

} 
} 
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An AppWindow Example 

This example shows how to create an AppWindow and obtain arguments from Workbench when the user drops 
an icon into it. The AppWindow will appear on the Workbench screen with the name "AppWindow" and will run 
until the window's close gadget is selected. If any icons are dropped into the AppWindow, the program prints 
their arguments in the Shell window. 

/* This example shows how to create an AppWindow and obtain arguments 

* from Workbench when the user drops an icon into it. The AppWindow 

* will appear on the Workbench screen with the name "AppWindow" and 

* will run until the window's close gadget is selected. If any icons 

* are dropped into the AppWindow, the program prints their arguments in 

* the Shell window. 
*/ 

/* appwindow.c - Compiled under SAS C 5.10 with lc -L appwindow.c */ 

/* Requires Kickstart version 37 or later. Works from the Shell (CLI) only */ 

#include <exec/types .h> /* Need this for the Amiga variable types */ 

#include <workbench/workbench.h> /* This has DiskObject and AppWindow */ 

#include <workbench/startup.h> /* This has WBStartup and WBArg structs */ 

#include <exec/libraries .h> /* Need this to check library versions */ 



#include <stdio.h> 

#include <clib/intuition_protos . h> 
#include <clib/exec_protos . h> 
#include <clib/wb_protos . h> 

#ifdef LATTICE 

int CXBRK(void) { return(O); } /* Disable SAS Lattice CTRL/C handling */ 

int chkabort (void) { return(O); }/* really */ 

#endif 

struct Library *IntuitionBase; 
struct Library *WorkbenchBase; 

void main (int argc, char **argv) 

{ 

struct MsgPort *awport; 
struct Window *win; 
struct AppWindow *appwin; 
struct IntuiMessage *imsg; 
struct AppMessage *amsg; 
struct WBArg *argptr; 

ULONG winsig, appwinsig, signals, id = 1, userdata = 0; 

BOOL done = FALSE; 

int i ; 

if (IntuitionBase = OpenLibrary ( "intuition. library" , 37)) 

{ 

if (WorkbenchBase = OpenLibrary ( "workbench. library" , 37)) 

{ 

/* The CreateMsgPort ( ) function is in Exec version 37 and later only */ 

if (awport = CreateMsgPort () ) 

{ 

if (win = OpenWindowTags (NULL, 

WA_Width, 200, WA_Height , 50, 

WA_IDCMP, CLOSEWINDOW, 

WA_Flags, WINDOWCLOSE | WINDOWDRAG, 

WA_Title, "AppWindow", 

TAG_DONE) ) 

{ 

if (appwin = AddAppWindow (id, userdata, win, awport, NULL)) 

{ 

printf ( "AppWindow added... Drag files into AppWindow\n" ) ; 
winsig = 1L << win->UserPort->mp_SigBit ; 
appwinsig = 1L << awport - >mp_SigBit ; 

while ( ! done) 

{ 

/* Wait for IDCMP messages and AppMessages */ 

signals = Wait ( winsig | appwinsig ) ; 

if (signals & winsig) /* Got an IDCMP message */ 

{ 

while (imsg = (struct IntuiMessage *) GetMsg (win->UserPort) ) 

{ 

if (imsg->Class = CLOSEWINDOW) done = TRUE ; 
ReplyMsg ( (struct Message *) imsg); 
} 
} 
if (signals & appwinsig) /* Got an AppMessage */ 

{ 

while (amsg = (struct AppMessage *) GetMsg (awport) ) 

{ 

printf ( "AppMsg: Type=%ld, ID=%ld, NumArgs=%ld\n" , 

amsg->am_Type, amsg->am_ID, amsg->am_NumArgs) ; 
argptr = amsg->am_ArgList ; 
for (i = 0; i < amsg->am_NumArgs ; i++) 

{ 

printf (" arg(%ld): Name='%s', Lock=%lx\n", 

i, argptr- >wa_Name, argptr- >wa_Lock) ; 
argptr++ ; 



ReplyMsg ( (struct Message *) amsg) ; 
} 
} 
} /* done */ 
RemoveAppWindow (appwin) ; 

} 
CloseWindow (win) ; 

} 
/* Make sure there are no more outstanding messages */ 
while(amsg = (struct AppMessage *) GetMsg (awport) ) 

ReplyMsg ( (struct Message *)amsg); 
DeleteMsgPort (awport) ; 

} 
CloseLibrary (WorkbenchBase) ; 

} 
CloseLibrary (IntuitionBase) ; 

} 
} 

Workbench and the Startup Code Module 

Standard startup code handles the detail work of interfacing with the arguments and environment of Workbench 
and the Shell (or CLI). This section describes the behavior of standard startup modules such as the ones 
supplied with SAS (Lattice) C and Manx Aztec C. 

The environment for a program started from Workbench is quite different from the environment for a program 
started from the Shell. The Shell does not create a new process for a program; it jumps to the program's code 
and the program shares the process with the Shell. Programs run under the Shell have access to all the Shell's 
environment, including the ability to modify that environment. (Programs run from the Shell should be careful to 
restore all values that existed on startup.) Workbench starts a program as a new DOS process, explicitly passing 
the execution environment to the program. 

Workbench Startup 

When the user activates a project or tool icon, the program is run as a separate process asynchronous to 
Workbench. This allows the user to take full advantage of the multitasking features of the Amiga. A process is 
simply a task with additional information needed to use DOS library. 

When Workbench loads and starts a program, its sends the program a WBStartup message containing the 
arguments as described earlier. The WBStartup also contains a pointer to the new Process structure which 
describes the execution environment of the program. The WBStartup message is posted to the message port of 
the program's Process structure. 

The Process message port is for the exclusive use of DOS, so this message must be removed from the port 
before using any DOS library functions. Normally this is handled by the startup code module that comes with your 
compiler so you don't have to worry about this unless you are writing your own startup code. 
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Standard startup code modules also set up SysBase, the pointer to the Exec master library, and open the DOS 
library setting up DOSBase. That is why Exec and AmigaDOS functions can be called by C applications without 
first opening a library; the startup code that applications are linked with handles this. Some special startups may 
also set up NIL: input and output streams, or may open a stdio window so that the Workbench applications can 
use stdio functions such as printf(). 

The startup code can tell if it is running in the Workbench environment because the pr_CLI field of the Process 
structure will contain NULL. In that case the startup code removes the WBStartup message from the Process 
message port with GetMsg() before using any functions in the DOS library. 

Do Not Use the Process Message Port for Anything Else. The message port in a Process 
structure is for the exclusive use of the DOS library. 

Standard startup code will pass the WBStartup message pointer in argv and (zero) in argc if the program is 
started from Workbench. These values are pushed onto the stack, and the startup code calls the application code 



that it is linked with as a function. When the application code exits back to the startup code, the startup code 
closes and frees all opens and allocations it made. It will then Forbid(), and ReplyMsgQ the WBStartup 
message, notifying Workbench that the application Process may be terminated and its code unloaded from 
memory. 

Avoid the DOS ExitQ function. The DOS Exit() function does not return an application to the 
startup code that called it. If you wish to exit your application, use the exit function provided 
by your startup code (usually lower-case exit(), or _exit for assembler), passing it a valid 
DOS return code as listed in the include file <libraries/dos.h>. 

Shell Startup 

When a program is started from the Shell (or a Shell script), standard startup modules will parse the command 
line (received in AO, with length in DO) into an array of pointers to individual argument strings placing them in 
argv, and an argument count in argc. 

If a program is started from the Shell, argc will always equal at least one and the first element in argv will always 
be a pointer to the command name. Other command line arguments are stored in turn. For example, if the 
command line was: 

dfO:myprogram "myfilel" file2 ;this is a comment 

then argc will be 3, argv[0] will be "dfO:myprogram", argv[1] will be "my filer, and argv[2] will be "file2". Correct 
startup code will strip spaces between arguments and trailing spaces from the last argument and will also properly 
deal with quoted arguments with embedded spaces. 

As with Workbench, standard startup code for the Shell sets up SysBase, the pointer to the Exec master library, 
and opens the DOS library setting up DOSBase. C applications that are linked with standard startup code can 
call an Exec or AmigaDOS functions without opening the library first. 

The startup code also fills in the stdio file handles (_stdin, _stdout, etc.) for the application. Finally argv and argc, 
are pushed onto the stack and the application is called via a JSR. When the application returns or exits back to 
the startup code, the startup code closes and frees all opens and allocations it has made for the application, and 
then returns to the system with the whatever value the program exited with. 
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Link your applications only with standard, tested startup code of some type such as the module supplied with your 
compiler. Startup code provides your programs with correct, consistent handling of Shell command line and 
Workbench arguments and will perform some initializations and cleanups which would otherwise need to be 
handled by your own code. Very small startups can be used for programs that do not require command line 
arguments. 

A few words of warning for those of you who do not use standard startup code: 

If you are started as a Workbench process, you must GetMsg() the WBStartup message before using 
any functions in the DOS library. 

You must turn off task switching (with ForbidQ) before replying the WBStartup message from 
Workbench. This will prevent Workbench from unloading your code before you can exit properly. 

If you do your own command line parsing, you must provide the user with consistent and correct 
handling of command line arguments. 



Function Reference 



The following are brief descriptions of the functions in workbench. library and icon. library. See the Amiga ROM 
Kernel Reference Manual: Includes and Autodocs for details on each function call. 



Table 14-3: Icon Library Functions 



Function 

GetDiskObject() 

GetDiskObjectNew() 
PutDiskObject() 
FreeDiskObject() 
DeleteDiskObject() 



Description 

Read the .info file of an icon into a Diskubject structure 

Same as GetDiskObject() but returns a default icon if none exists 

Write a DiskObject structure to disk as a .info file 

Free the DiskObject structure created by GetDiskObject() 

Deletes a given .info file from disk 



hinciiooi iype() 
MatchToolValueQ 



Heturn the value of an entry in the icon's I ool I ype array 
Check a Tool Type entry against a given value 



UetUetUiskObject() 
PutDefDiskObjectQ 



Head the default icon tor a given icon type 
Replace the default icon for a given icon type (V36) 



AddFreeLlst() — 

FreeFreeList() 

BumpRevisionQ 



"Aden 



have allocated to a FreeList 



memory you 
Free all the memory for entries in the FreeList 
Create a new name for a second copy of a Workbench object 



Table 14-4: Workbench Library Functions 



Function 



AddApplcon() 

AddAppMenultem() 

AddAppWindowQ 



Description 



Add an Applcon to Workbench 

Add an AppMenultem to the Workbench Tools menu 

Add an AppWindow to Workbench 



HemoveApplcon() 

RemoveAppMenultem() 

RemoveAppWindow() 



Remove an Applcon to Workbench 

Remove an AppMenultem to the Workbench Tools menu 

Remove an AppWindow to Workbench 



Chapter 15 
Gadtools Library 



GadTools is a new library in Release 2 that is designed to simplify the task of creating user interfaces with 
Intuition. GadTools offers a flexible and varied selection of gadgets and menus to help programmers through 
what used to be a difficult chore. 

Intuition, the Amiga's graphical user interface, is a powerful and flexible environment. It allows a software 
designer a great degree of flexibility in creating dynamic and powerful user interfaces. However, the drawback of 
this flexibility is that programming even straightforward user interfaces can be complicated, and certainly difficult 
for first-time Intuition programmers. 

What the Gadget Toolkit (GadTools) attempts to do is harness the power of Intuition by providing easy-to-use, 
high-level chunks of user interface. GadTools doesn't pretend to answer all possible user interface needs of every 
application but by meeting the user interface needs of most applications, GadTools greatly simplifies the problem 
of designing user-friendly software on the Amiga. (For applications with special needs, custom solutions can be 
created with Intuition's already-familiar gadgets or its new Boopsi object-oriented custom gadget system; 
GadTools is compatible with these.) 



Elements of GadTools 



GadTools is the easy way to program gadgets and menus. With GadTools, the system handles the detail work 
required to control gadgets and menus so the application uses less code and simpler data structures. 

Another key benefit of GadTools is its standardized and elegant look. All applications that use GadTools will 
share a similar appearance and behavior. Users will appreciate a sense of instant familiarity even the first time 
they use a product. 

GadTools provides a significant degree of visual consistency across multiple applications that use it. For 
instance, in Release 2, the Preferences editors, the Workbench "Information" window and Commodities Exchange 
share the same polished look and feel thanks to GadTools. There is also internal consistency between different 
elements of GadTools; the look is clean and orderly. Depth is used not just for visual embellishment, but as an 
important cue. For instance, the user is free to select symbols that appear inside a "raised" area, but "recessed" 
areas are informational only, and clicking in them has no effect. 
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GadTools is not amenable to creative post-processing or hacking by programmers looking to achieve a result 
other than what GadTools currently offers. Software developers whose needs extend beyond the standard 
features of GadTools should create custom gadgets that share the look and feel of GadTools by using either 
BOOPSI or by directly programming gadgets at a lower level. See the chapters on "Intuition Gadgets" and 
"BOOPSI" for more information. Follow the GadTools rules. Only in this way may GadTools grow and improve 
without hindrance, even allowing new features to automatically appear in future software when reasonable. 

GadTools Tags 

Many of the GadTools functions use Tagltem arrays or tag lists\o pass information across the function interface. 
These tag-based functions come in two types, one that takes a pointer to an array of tag items and one that takes 
a variable number of tag item arguments directly in the function call. In general, the second form, often called the 
varargs form because the call takes a variable number of arguments, is provided for convenience and is internally 
converted to the first form. When looking through the Autodocs or other Amiga reference material, the 
documentation for both forms is usually available in the array-based function description. 

All GadTools tags begin with a leading "GT". In general, they also have a two-letter mnemonic for the kind of 
gadget in question. For example, slider gadgets recognize tags such as "GTSL_Level". The GadTools tags are 
defined in <libraries/gadtools.h>. Certain GadTools gadgets also recognize other Intuition tags such as 
GA_Disabled and PGA_Freedom, which can be found in <intuition/gadgetclass.h>. 



For more information on tags and tag-based functions, be sure to see the "Utility Library" chapter in this manual. 



GadTools Menus 



GadTools menus are easy to use. Armed only with access to a Visuallnfo data structure, GadTools allows the 
application to easily create, layout and delete Intuition menus. 

Normally, the greatest difficulty in creating menus is that a large number of structures must be filled out and 
linked. This is bothersome since much of the required information is orderly and is easier to do algorithmically 
than to do manually. GadTools handles this for you. 

There are also many complexities in creating a sensible layout for menus. This includes some mechanical items 
such as handling various font sizes, automatic columnization of menus that are too tall and accounting for space 
for checkmarks and Amiga-key equivalents. There are also aesthetic considerations, such as how much spacing 
to provide, where sub-menus should be placed and so on. 

GadTools menu functions support all the features that most applications will need. These include: 

An easily constructed and legible description of the menus. 

Font-sensitive layout. 

Support for menus and sub-menus. 
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Sub-menu indicators (a "»" symbol attached to items with sub-menus). 

Separator bars for sectioning menus. 

Command-key equivalents. 

Checkmarked and mutually exclusive checkmarked menu items. 

Graphical menu items. 

With GadTools, it takes only one structure, the NewMenu structure, to specifiy the whole menu bar, For instance, 
here is how a typical menu strip containing two menus might be specified: 

struct NewMenu mynewmenu[] = 



{ NMJTITLE, 


"Project" , 





o, 


o, 


o,}, 


{ NM_ITEM, 


"Open. . . ", 


"0" 


o, 


o, 


0,}, 


{ NM_ITEM, 


"Save", 


"S" 


o, 


o, 


0,}, 


{ NM_ITEM, 


NM_BARLABEL , 





o, 


o. 


0,}, 


{ NM_ITEM, 


"Print" , 





o, 


o, 


0,}, 


{ NM_SUB , 


"Draft" , 





o, 


o, 


0,}, 


{ NM_SUB , 


"NLQ", 





o, 


o, 


0,}, 


{ NM_ITEM, 


NM_BARLABEL , 





o, 


o, 


0,}, 


{ NM_ITEM, 


"Quit. 


"Q" 


o, 


o, 


0,}, 


{ NMJTITLE, 


"Edit", 





o, 


o, 


o,}, 


{ NM_ITEM, 


"Cut", 


"X" 


o, 


o, 


0,}, 


{ NM_ITEM, 


"Copy", 


"C" 


o, 


o, 


0,}, 


{ NM_ITEM, 


"Paste", 


"V" 


o, 


o, 


0,}, 


{ NM_ITEM, 


NM_BARLABEL , 





o, 


o, 


0,}, 


{ NM_ITEM, 


"Undo" , 


"Z" 


o, 


o, 


0,}, 



}; 



NM END, NULL, 



0,0,0, 0,}, 



This NewMenu specification would produce the two menus below: 




Figure 15-1 : Two Example Menus 
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The NewMenu arrays are designed to be read easily. The elements in the NewMenu array appear in the same 
order as they will appear on-screen. Unlike the lower-level menu structures described in the "Intuition Menus" 
chapter earlier, there is no need to specify sub-menus first, then the menu items with their sub-menus, and finally 
the menu headers with their menu items. The indentation shown above also helps highlight the relationship 
between menus, menu items and sub-items. 

The NewMenu Structure 

The NewMenu structure used to specify GadTools menus is defined in <libraries/gadtools.h> as follows: 

struct NewMenu 

{ 

UBYTE nm_Type; 

STRPTR nm_Label; 

STRPTR nm_CommKey; 

UWORD nm_Flags; 

LONG nm_MutualExclude; 

APTR nm_UserData; 

}; 



nm_Type 



The first field, nm_Type, defines what this particular NewMenu describes. The defined types provide 
an unambiguous and convenient representation of the application's menus. 



NMJTITLE 

Used to signify a textual menu heading, 
menu within the menu strip. 



Each NM_TITLE signifies the start of a new 



NMJTEM or IMJTEM 

Used to signify a textual (NMJTEM) or graphical (IMJTEM) menu item. Each 
NMJTEM or IMJTEM becomes a menu item in the current menu. 

NMJ3UB or IMJ3UB 

Used to signify a textual (NM_SUB) or graphical (IM_SUB) menu sub-item. All the 
consecutive NM_SUBs and IMJSUBs that follow a menu item (NMJTEM or IMJTEM) 
compose that item's sub-menu. A subsequent NMJTEM or IMJTEM would indicate 
the start of the next item in the original menu, while a subsequent NMJTITLE would 
begin the next menu. 



NM_END 

Used to signify the end of the NewMenu structure array. The last element of the array 
must have NM_END as its type. 

nmLabel 

NM_TITLE, NMJTEM and NM_SUB are used for textual menu headers, menu items and sub-items 
respectively, in which case nm_Label points to the string to be used. This string is not copied, but 
rather a pointer to it is kept. Therefore the string must remain valid for the active life of the menu. 

Menus don't have to use text, GadTools also supports graphical menu items and sub-items (graphical 
menu headers are not possible since they are not supported by Intuition). Simply use IMJTEM and 
IM_SUB instead and point nm_Label at a valid Image structure. The Image structure can contain just 
about any graphic image (see the chapter on "Intuition Images, Line Drawing and Text" for more on 
this). 
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Sometimes it is a good idea to put a separator between sets of menu items or sub-items. The 
application may want to separate drastic menu items such as "Quit" or "Delete" from more mundane 
ones. Another good idea is to group related checkmarked items by using separator bars. 

NM_BARLABEL 

GadTools will provide a separator bar if the special constant NM_BARLABEL is 
supplied for the nmLabel field of an NMJTEM or NMSUB. 

nm_CommKey 

A single character string used as the Amiga-key equivalent for the menu item or sub-item. 

Menu headers cannot have command keys. Note that assigning a command-key equivalent to a menu 
item that has sub-items is meaningless and should be avoided. 

The nm_CommKey field is a pointer to a string and not a character itself. This was done in part 
because routines to support different languages typically return strings, not characters. The first 
character of the string is actually copied into the resulting Menultem structure. 

nm_Flags 

The nmFlags field of the NewMenu structure corresponds roughly to the Flags field of the Intuition's 
lower-level Menu and Menultem structures. 

For programmer convenience the sense of the Intuition MENUENABLED and ITEMENABLED flags are 
inverted. When using GadTools, menus, menu items and sub-items are enabled by default. 

NM_MENUDISABLED 

To specify a disabled menu, set the NM_MENUDISABLED flag in this field. 

NMJTEMDISABLED 

To disable an item or sub-item, set the NMJTEMDISABLED flag. 

The Intuition flag bits COMMSEQ (indication of a command-key equivalent), ITEMTEXT (indication of a 
textual or graphical item) and HIGHFLAGS (method of highlighting) will be automatically set depending 
on other attributes of the menus. Do not set these values in nmj=lags. 

The nmj=lags field is also used to specify checkmarked menu items. To get a checkmark that the 
user can toggle, set the CHECKIT and MENUTOGGLE flags in the nmFlags field. Also set the 
CHECKED flag if the item or sub-item is to start in the checked state. 

nmMutualExclude 

For specifying mutual exclusion of checkmarked items. All the items or sub-items that are part of a 
mutually exclusive set should have the CHECKIT flag set. 

This field is a bit-wise representation of the items (or sub-items), in the same menu or sub-menu, that 
are excluded by this item (or sub-item). In the simple case of mutual exclusion, where each choice 
excludes all others, set nm MutualExclude to ~(1«item number) or ~1, ~2, ~4, ~8, etc. Separator 



bars count as items and should be included in the position calculation. See the "Intuition Menus" 
chapter for more details on menu mutual exclusion. 
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nm_UserData 

The NewMenu structure also has a user data field. This data is stored with the Intuition Menu or 
Menultem structures that GadTools creates. Use the macros GTMENU_USERDATA(menu) and 
GTMENUITEM USERDATA(menuitem) defined in <libraries/gadtools.h> to extract or change the user 
data fields of menus and menu items, respectively. 

The application may place index numbers in this field and perform a switch statement on them, instead 
of using the Intuition menu numbers. The advantage of this is that the numbers chosen remain valid 
even if the menus are rearranged, while the Intuition menu numbers would change when the menus 
are rearranged. 

Alternately, an efficient technique for menu handling is to create a handler function for each menu item 
and put a pointer to that function in the corresponding item's UserData field. When the program 
receives a IDCMP_MENUPICK message it may call the selected item's function through this field. 

GadTools Menus Example 

The function used to set up and control GadTools menus are discussed in the next section. Before looking at 
these functions in detail, it may be helpful to look at a brief example. 

/* The functions used to set up and control GadTools menus are discussed 

* in the next section. Before looking at these functions in detail, it 

* may be helpful to look at a brief example. 
*/ 

/* gadtoolsmenu.c 

** Example showing the basic usage of the menu system with a window. 

** Menu layout is done with GadTools, as is recommended for applications. 



• * 

• * 



Compiled with SAS C v5.10a 



** lc -bl -cfistq -v -y gadtoolsmenu 



• * 



blink FROM LIB:c.o gadtoolsmenu . o TO gadtoolsmenu LIB LIB :1c. lib LIB : amiga . lib 



#define INTUI_V3 6_NAMES_ONLY 

#include <exec/types .h> 
#include <intuition/intuition.h> 
#include <intuition/intuitionbase . h> 
#include <libraries/gadtools . h> 

#include <clib/exec_protos . h> 
#include <clib/gadtools_protos . h> 
#include <clib/intuition_protos . h> 

#include <stdio.h> 

#ifdef LATTICE 

int CXBRK(void) { return(O); } /* Disable Lattice CTRL/C handling */ 

int chkabort (void) { return(O); } /* really */ 

#endif 

struct Library *GadToolsBase; 
struct IntuitionBase *IntuitionBase; 

struct NewMenu mynewmenut] = 
{ 



{ NM_TITLE, 


"Project" , 





0, 


0, 





} 


{ NM_ITEM, 


"Open. . . " , 


"0" 


0, 


0, 





} 


{ NM_ITEM, 


"Save" , 


"S" 


0, 


0, 





} 


{ NM_ITEM, 


NM_BARLABEL , 





0, 


0, 





} 


{ NM_ITEM, 


"Print" , 





0, 


0, 





} 


{ NM_SUB , 


"Draft" , 





0, 


0, 





} 



{ NM_SUB , 


"NLQ" , 





0, 


0, 


0, } 


{ NM ITEM, 


NM_BARLABEL , 





0, 


0, 


0, } 


{ NM_ITEM, 


"Quit . . . " , 


"Q" 


0, 


0, 


0, } 


{ NM TITLE, 


"Edit", 





0, 


0, 


0, } 


{ NM_ITEM, 


"Cut" , 


"X" 


0, 


0, 


0, } 


{ NM_ITEM, 


"Copy", 


"C" 


0, 


0, 


0, } 


{ NM_ITEM, 


"Paste" , 


"V" 


0, 


0, 


0, } 


{ NM ITEM, 


NM_BARLABEL , 





0, 


0, 


0, } 


{ NM ITEM, 


"Undo", 


ii z ii 


0, 


0, 


0, } 



}; 



NM END, NULL, 



0, 0, 0, } , 



/* 

** Watch the menus and wait for the user to select the close gadget 

** or quit from the menus. 

*/ 

VOID handle_window_events (struct Window *win, struct Menu *menuStrip) 

{ 

struct IntuiMessage *msg; 

SHORT done; 

UWORD menuNumber; 

UWORD menuNum; 

UWORD itemNum; 

UWORD subNum; 

struct Menultem *item; 



done = FALSE; 
while (FALSE = 



done) 



/* we only have one signal bit, so we do not have to check which 
** bit broke the Wait(). 

*/ 

Wait(lL << win->UserPort->mp_SigBit) ; 

while ( (FALSE == done) && 

(NULL != (msg = (struct IntuiMessage *) GetMsg (win->UserPort) ) ) ) 

{ 

switch (msg->Class) 

{ 

case IDCMP_CLOSEWINDOW: 

done = TRUE ; 

break; 
case IDCMPJVIENUPICK: 

menuNumber = msg->Code; 

while ((menuNumber != MENUNULL) && (!done)) 

{ 

item = ItemAddress (menuStrip, menuNumber) ; 

/* process the item here! */ 
menuNum = MENUNUM (menuNumber) ; 
itemNum = ITEMNUM (menuNumber) ; 
subNum = SUBNUM (menuNumber) ; 



/* stop if quit is selected. */ 
if ( (menuNum == 0) && (itemNum = 
done = TRUE ; 



5) ) 



menuNumber = item->NextSelect ; 
} 



break; 



ReplyMsg ( (struct Message *)msg); 



} 



/* 

** Open all of the required libraries and set-up the menus. 

*/ 

VOID main(int argc, char *argv[]) 



{ 

struct Window *win; 
APTR *my_VisualInfo; 
struct Menu *menuStrip; 

/* Open the Intuition Library */ 

IntuitionBase = (struct IntuitionBase *) OpenLibrary ( "intuition. library" , 37); 

if (IntuitionBase != NULL) 

{ 

/* Open the gadtools Library */ 

GadToolsBase = OpenLibrary ( "gadtools . library" , 37); 

if (GadToolsBase != NULL) 

{ 

if (NULL != (win = OpenWindowTags (NULL, 

WA_Width, 400, WA_Activate, TRUE, 

WA_Height, 100, WA_CloseGadget , TRUE, 

WA_Title, "Menu Test Window", 

WA_IDCMP, IDCMP_CLOSEWINDOW | IDCMP_MENUPICK, 

TAG_END) ) ) 

{ 

if (NULL != (my_VisualInfo = GetVisuallnf o (win->WScreen, TAG_END) ) ) 

{ 

if (NULL != (menuStrip = CreateMenus (mynewmenu, TAG_END) ) ) 

{ 

if (LayoutMenus (menuStrip, my_VisualInf o, TAG_END) ) 

{ 

if (SetMenuStrip (win, menuStrip)) 

{ 

handle_window_events (win, menuStrip) ; 

ClearMenuStrip (win) ; 

} 
FreeMenus (menuStrip) ; 

} 
} 
FreeVisuallnf o (my_VisualInf o) ; 

} 
CloseWindow (win) ; 

} 
CloseLibrary ( (struct Library *) GadToolsBase) ; 

} 
CloseLibrary ( (struct Library *) IntuitionBase) ; 

} 
} 

Functions For GadTools Menus 

In this section the basic GadTools menu functions are presented. See the listing above for an example of how to 
use these functions. 

Creating Menus 

The CreateMenusQ function takes an array of NewMenus and creates a set of initialized and linked Intuition 
Menu, Menultem, Image and IntuiText structures, that need only to be formatted before being used. Like the 
other tag-based functions, there is a CreateMenusAQ call that takes a pointer to an array of Tagltems and a 
CreateMenus() version that expects to find its tags on the stack. 

struct Menu *CreateMenusA ( struct NewMenu *newmenu, struct Tagltem *taglist ) ; 
struct Menu *CreateMenus ( struct NewMenu *newmenu, Tag tagl , ... ) ; 

The first argument to these functions, newmenu, is a pointer to an array of NewMenu structures as described 
earlier. The tag arguments can be any of the following items: 

GTMN_FrontPen (ULONG) 

The pen number to use for menu text and separator bars. The default is zero. 

GTMN_FullMenu (BOOL) 

(New for V37, ignored under V36). This tag instructs CreateMenusQ to fail if the supplied NewMenu 
structure does not describe a complete Menu structure. This is useful if the application does not have 



direct control over the NewMenu description, for example if it has user-configurable menus. The 
default is FALSE. 

374 Amiga ROM Kernel Reference Manual: Libraries 

GTMN_SecondaryError (ULONG *) 

(New for V37, ignored under V36). This tag allows CreateMenusQ to return some secondary error 
codes. Supply a pointer to a NULL-initialized ULONG, which will receive an appropriate error code 
as follows: 

GTMENUJNVALID 

Invalid menu specification. For instance, a sub-item directly following a menu-title or 
an incomplete menu. CreateMenus() failed in this case, returning NULL. 

GTMENU_NOMEM 

Failed for lack of memory. CreateMenus() returned NULL. 

GTMENU_TRIMMED 

The number of menus, items or sub-items exceeded the maximum number allowed so 
the menu was trimmed. In this case, CreateMenusQ does not fail but returns a 
pointer to the trimmed Menu structure. 



NULL 



If no error was detected. 



CreateMenus() returns a pointer to the first Menu structure created, while all the Menultem structures and any 
other Menu structures are attached through the appropriate pointers. If the NewMenu structure begins with an 
entry of type NMJTEM or IMJTEM, then CreateMenus() will return a pointer to the first Menultem created, since 
there will be no first Menu structure. If the creation fails, usually due to a lack of memory, CreateMenus() will 
return NULL. 

Starting with V37, GadTools will not create any menus, menu items or sub-items in excess of the maximum 
number allowed by Intuition. Up to 31 menus may be defined, each menu with up to 63 items, each item with up 
to 31 sub-items. See the "Intuition Menus" chapter for more information on menus and their limitations. If the 
NewMenu array describes a menu that is too big, CreateMenusQ will return a trimmed version. 
GTMN_SecondaryError can be used to learn when this happens. 

Menus need to be added to the window with Intuition's SetMenuStrip() function. Before doing this, they must be 
formatted with a call to LayoutMenus(). 

Layout of the Menus 

The Menu and Menultem structures returned by CreateMenusQ contain no size or positional information. This 
information is added in a separate layout step, using LayoutMenus(). As with the other tag-based functions, the 
program may call either LayoutMenus() or LayoutMenusA(). 

BOOL LayoutMenusA ( struct Menu *firstmenu, APTR vi, struct Tagltem *taglist ) ; 
BOOL LayoutMenus ( struct Menu *firstmenu, APTR vi , Tag tagl , ... ) ; 

Set firstmenu to a pointer to a Menu structure returned by a previous call to CreateMenus(). The vi argument is 
a a Visuallnfo handle obtained from GetVisuallnfo(). See the documentation of GadTools gadgets below for 
more about this call. For the tag arguments, tagl or taglist, LayoutMenus() recognizes a single tag: 

GTMN_TextAttr 

A pointer to an openable font (TextAttr structure) to be used for the menu item and sub-item text. The 
default is to use the screen's font. 
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LayoutMenus() fills in all the size, font and position information for the menu strip. LayoutMenus() returns 
TRUE if successful and FALSE if it fails. The usual reason for failure is that the font supplied cannot be opened. 

LayoutMenus() takes care of calculating the width, height and position of each individual menu item and 
sub-item, as well as the positioning of all menus and sub-menus. In the event that a menu would be too tall for 



the screen, it is broken up into multiple columns. Additionally, whole menus may be shifted left from their normal 
position to ensure that they fit on screen. If a large menu is combined with a large font, it is possible, even with 
columnization and shifting, to create a menu too big for the screen. GadTools does not currently trim off excess 
menus, items or sub-items, but relies on Intuition to clip menus at the edges of the screen. 

It is perfectly acceptable to change the menu layout by calling ClearMenuStripQ to remove the menus, then 
LayoutMenusQ to make the change and then SetMenuStrip() to display the new layout. Do this when changing 
the menu's font (this can be handled by a tag to LayoutMenus()), or when updating the menu's text (to a different 
language, for instance). Run-time language switching in menus will be discussed later. 

Layout of Individual Menus 

LayoutMenultemsQ performs the same function as LayoutMenus(), but only affects the menu items and 
sub-items of a single menu instead of the whole menu strip. Ordinarily, there is no need to call this function after 
having called LayoutMenusQ. This function is useful for adding menu items to an extensible menu, such as the 
Workbench "Tools" menu. 

For example, a single Menultem can be created by calling CreateMenus() with a two-entry NewMenu array 
whose first entry is of type NMJTEM and whose second is of type NM_END. The menu strip may then be 
removed and this new item linked to the end of an extensible menu by placing its address in the Nextltem field of 
the last Menultem in the menu. LayoutMenultemsQ can then be used to to recalculate the layout of just the 
items in the extensible menu and, finally, the menu strip can be reattached to the window. 

BOOL LayoutMenuItemsA( struct Menultem *firstitem, APTR vi , struct Tagltem *taglist) ; 
BOOL LayoutMenuI terns ( struct Menultem *firstitem, APTR vi , Tag tagl, ... ); 

Set firstitem to a pointer to the first Menultem in the linked list of Menultems that make up the Menu. (See the 
"Intuition Menus" chapter for more about these structures.) Set vi to the address of a Visuallnfo handle obtained 
from GetVisuallnfo(). The tag arguments, tagl or taglist, may be set as follows: 

GTMN_TextAttr 

A pointer to an openable font (TextAttr structure) to be used for the menu item and sub-item text. The 
default is to use the screen's font. 

GTMN_Menu 

Use this tag to provide a pointer to the Menu structure whose Firstitem is passed as the first 
parameter to this function. This tag should always be used. 

LayoutMenultemsQ returns TRUE if it succeeds and FALSE otherwise. 
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Freezing Menus 

The FreeMenusQ function frees all the memory allocated by the corresponding call to CreateMenus(). 

void FreeMenus ( struct Menu *menu ) ; 

Its one argument is the Menu or Menultem pointer that was returned by CreateMenusQ. It is safe to call 
FreeMenusQ with a NULL parameter, the function will then return immediately. 

GadTools Menus and I ntui Messages 

If the window uses GadTools menus and GadTools gadgets, then use the GT_GetlMsg() and GT_ReplylMsg() 
functions described below (or GT_FilterlMsg() and GT_PostFilterlMsg(), if applicable). However, if the window 
has GadTools menus, but no GadTools gadgets, it is acceptable to use GetMsg() and ReplyMsgQ in the usual 
manner. 

Additionally, no context need be created with CreateContextQ if no GadTools gadgets are used. For more about 
these functions, see the section on "Other GadTools Functions" later in this chapter. 

Restrictions on GadTools Menus 

GadTools menus are regular Intuition menus. Once the menus have been laid out, the program may do anything 



with them, including attaching them or removing them from windows, enabling or disabling items, checking or 
unchecking checkmarked menu items, etc. See the documentation for SetMenuStripQ, ClearMenuStrip(), 
ResetMenuStripO, OnMenu() and OffMenu() in the "Intuition Menus" chapter for full details. 

If a GadTools-created menu strip is not currently attached to any window, the program may change the text in the 
menu headers (Menu->MenuName), the command-key equivalents (Menultem->Command) or the text or 
imagery of menu items and sub-items, which can be reached as: 



or 



(struct IntuiText *) MenuItem->ItemFill) ->IText 



(struct Image *) MenuItem->ItemFill) 



The application may also link in or unlink menus, menu items or sub-items. However, do not add sub-items to a 
menu item that was not created with sub-items and do not remove all the sub-items from an item that was created 
with some. 

Any of these changes may be made, provided the program subsequently calls LayoutMenus() or 
LayoutMenultems() as appropriate. Then, reattach the menu strip using SetMenuStrip(). 

Some of these manipulations require walking the menu strip using the usual Intuition-specified linkages. 
Beginning with the first Menu structure, simply follow its Firstltem pointer to get to the first Menultem. The 
Menultem->Subltem pointer will lead to the sub-menus. Menultems are connected via the 
Menultem->Nextltem field. Successive menus are linked together with the Menu->NextMenu pointer. Again, 
see the chapter "Intuition Menus" for details. 
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Language-Sensitive Menus 



Allowing the application to switch the language displayed in the menus, can be done quite easily. Simply detach 
the menu strip and replace the strings in the IntuiText structures as described above. It may be convenient to 
store some kind of index number in the Menu and Menultem UserData which can be used to retrieve the 
appropriate string for the desired language. After all the strings have been installed, call LayoutMenus() and 
SetMenuStripQ. 

If the application has the localized strings when the menus are being created, it simply places the pointers to the 
strings and command shortcuts into the appropriate fields of the NewMenu structure. The menus may then be 
processed in the normal way. 



GadTools Gadgets 



The heart of GadTools is in its ability to easily create and manipulate a sophisticated and varied array of gadgets. 
GadTools supports the following kinds of gadgets: 

Table 15-1 : Standard Gadget Types Supported by the GadTools Library 



Gadget Type 


Description or Example Usage 


Button 


Familiar action gadgets, such as "OK" or "Cancel". 


String 


For text entry. 


Integer 


For numeric entry. 


Checkboxes 


For on/off items. 


Mutually exclusive 


Radio buttons, select one choice among several. 


Cycle 


Multiple-choice, pick one of a small number of choices. 


Sliders 


To indicate a level within a range. 


Scrollers 


To indicate a position in a list or area. 


Listviews 


Scrolling lists of text. 


Palette 


Color selection. 


Text-display 


Read-only text. 


Numeric-display 


Read-only numbers. 



GadTools gadget handling consists of a body of routines to create, manage and delete any of the 12 kinds of 
standard gadgets listed in table 15-1 , such as buttons, sliders, mutually exclusive buttons and scrolling lists. 



To illustrate the flexibility, power and simplicity that GadTools offers, consider the GadTools slider gadget. This 
gadget is used to indicate and control the level of something, for example volume, speed or color intensity. 
Without GadTools, applications have to deal directly with Intuition proportional and their arcane variables, such as 
HorizBody to control the slider knob's size and HorizPot to control the knob's position. Using the GadTools 
slider allows direct specification of the minimum and maximum levels of the slider, as well as its current level. For 
example, a color slider might have a minimum level of 0, a maximum level of 1 5 and a current level of 1 1 . 

To simplify event-processing for the slider, GadTools only sends the application a message when the knob has 
moved far enough to cause the slider level, as expressed in application terms, to change. If a user were to slowly 
drag the knob of this color slider all the way to the right, the program will only hear messages for levels 12, 13, 14 
and 15, with an optional additional message when the user releases the mouse-button. 
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Changing the current level of the slider from within the program is as simple as specifying the new level in a 
function call. For instance, the application might set the slider's value to 5. 

As a final point, the slider is very well-behaved. When the user releases the mouse-button, the slider immediately 
snaps to the centered position for the level. If a user sets their background color to light gray, which might have 
red = green = blue = 10, all three color sliders will have their knobs at precisely the same relative position, instead 
of anywhere in the range that means "ten". 

The NewGadget Structure 

For most gadgets, the NewGadget structure is used to specify its common attributes. Additional attributes that 
are unique to specific kinds of gadgets are specified as tags sent to the CreateGadget() function (described 
below). 

The NewGadget structure is defined in <libraries/gadtools.h> as: 

struct NewGadget 

{ 

WORD ng_L eft Edge, ng_TopEdge; 

WORD ng_Width, ng_Height; 

UBYTE *ng_GadgetText ; 

struct TextAttr *ng_TextAttr ; 

UWORD ng_GadgetID; 

ULONG ng_Flags; 

APTR ng_VisualInfo; 

APTR ng_UserData; 

}; 
The fields of the NewGadget structure are used as follows: 

ng_LeftEdge, ng_TopEdge 

Define the position of the gadget being created. 

ng_Width and ngJHeight 

Define the size of the gadget being created. 

ng_GadgetText 

Most gadgets have an associated label, which might be the text in a button or beside a checkmark. 
This field contains a pointer to the appropriate string. Note that only the pointer to the text is copied, 
the text itself is not. The string supplied must remain constant and valid for the life of the gadget. 

ng_TextAttr 

The application must specify a font to use for the label and any other text that may be associated with 
the gadget. 

ng Flags 

Used to describe general aspects of the gadget, which includes where the label is to be placed and 
whether the label should be rendered in the highlight color. The label may be positioned on the left 
side, the right side, centered above, centered below or dead-center on the gadget. For most gadget 
kinds, the label is placed on the left side by default, exceptions will be noted. 



ng_GadgetlD, ng User Data 

These user fields are copied into the resulting Gadget structure. 

GadTools Library 379 

ngVlsuallnfo 

This field must contain a pointer to an instance of the Visuallnfo structure, which contains information 
needed to create and render GadTools gadgets. The Visuallnfo structure itself is private to GadTools 
and subject to change. Use the specialized GadTools functions for accessing the Visuallnfo pointer, 
defined below. Never access or modify fields within this structure. 

Creating Gadgets 

The main call used to create a gadget with GadTools is CreateGadget(). This function can be used to create a 
single gadget or it can be called repeatedly to create a linked list of gadgets. It takes three arguments followed by 
a set of tags: 

struct Gadget *CreateGadget ( ULONG kind, struct Gadget *prevgad, 

struct NewGadget *newgad, struct Tagltem *taglist) 

struct Gadget *CreateGadgetA (ULONG kind, struct Gadget *prevgad, 

struct NewGadget *newgad, struct Tag tagl, ...) 

Set the kind argument to one of the 12 gadget types supported by GadTools. Set the prevgad argument to the 
gadget address returned by CreateContext() if this is the first (or only) gadget in the list. Subsequent calls to 
CreateGadget() can be used to create and link gadgets together in a list in which case the prevgad argument is 
set to the address of the gadget returned by the preceding call to CreateGadget(). 

Set the newgad argument to the address of the NewGadget structure describing the gadget to be created and 
set any special attributes for this gadget type using the tag arguments, tagl or taglist. For instance, the following 
code fragment might be used to create the color slider discussed earlier: 

slidergad = CreateGadget (SLIDER_KIND, newgadget, prevgad, 
GTSL_Min, 0, 
GTSL_Max, 15, 
GTSL_Level, 11, 
TAG_END) ; 

CreateGadget() typically allocates and initializes all the necessary Intuition structures, including in this case the 
Gadget, IntuiTextand Proplnfo structures, as well as certain buffers. For more about these underlying 
structures, see the "Intuition Gadgets" chapter. 

Since CreateGadget() is a tag-based function, it is easy to add more tags to get a fancier gadget. For example, 
GadTools can optionally display the running level beside the slider. The caller must supply a printf()-style 
formatting string and the maximum length that the string will resolve to when the number is inserted: 

slidergad = CreateGadget (SLIDER_KIND, newgadget, prevgad, 
GTSL_Min, 0, 
GTSL_Max, 15, 
GTSL_Level, 11, 

GTSL_LevelFormat , "%21d" /* printf () -style formatting string */ 
GTSL_MaxLevelLen, 2, /* maximum length of string */ 
TAG_END) ; 

The level, to 15 in this example, would then be displayed beside the slider. The formatting string could instead 
be "%2ld/15", so the level would be displayed as "0/15" through "15/15". 
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Handling Gadget Messages 

GadTools gadgets follow the same input model as other Intuition components. When the user operates a 
GadTools gadget, Intuition notifies the application about the input event by sending an IntuiMessage. The 
application can get these messages at the Window.UserPort. However GadTools gadgets use different 



message handling functions to get and reply these messages. Instead of the Exec functions GetMsg() and 
ReplyMsg(), applications should get and reply these messages through a pair of special GadTools functions, 
GT_GetlMsg() and GT_ReplylMsg(). 

struct IntuiMessage *GT_GetIMsg (struct MsgPort *iport) 
void GT_ReplyIMsg (struct IntuiMessage *imsg) 

For GT_GetlMsg(), the iport argument should be set to the window's UserPort. For GT_ReplylMsg(), the imsg 
argument should be set to a pointer to the IntuiMessage returned by GT_GetlMsg(). 

These functions ensure that the application only sees the gadget events that concern it and in a desirable form. 
For example, with a GadTools slider gadget, a message only gets through to the application when the slider's 
level actually changes and that level can be found in the IntuiMessage's Code field: 

imsg = GT_GetIMsg (win->UserPort) ; 
object = imsg->IAddress ; 
class = imsg->Class ; 
code = imsg->Code; 
GT_ReplyIMsg(imsg) ; 
switch (class) 

{ 

case IDCMP_MOUSEMOVE : 

if (object == slidergad) 

{ 

printf ( "Slider at level %ld\n", code); 

} 
break ; 

}" 

In general, the IntuiMessages received from GadTools contain more information in the Code field than is found 
in regular Intuition gadget messages. Also, when dealing with GadTools a lot of messages (mostly 
IDCMP_MOUSEMOVEs) do not have to be processed by the application. These are two reasons why dealing 
with GadTools gadgets is much easier than dealing with regular Intuition gadgets. Unfortunately this processing 
cannot happen magically, so applications must use GT_GetlMsg() and GT_ReplylMsg() where they would 
normally have used GetMsg() and ReplyMsg(). 

GT_GetlMsg() actually calls GetMsg() to remove a message from the specified window's UserPort. If the 
message pertains to a GadTools gadget then some dispatching code in GadTools will be called to process the 
message. What the program will receive from GT_GetlMsg() is actually a copy of the real IntuiMessage, 
possibly with some supplementary information from GadTools, such as the information typically found in the Code 
field. 

The GT_ReplylMsg() call will take care of cleaning up and replying to the real IntuiMessage. 

Warning: When an IDCMP_MOUSEMOVE message is received from a GadTools gadget, 
GadTools arranges to have the gadget's pointer in the lAddress field of the IntuiMessage. 
While this is extremely convenient, it is also untrue of messages from regular Intuition gadgets 
(described in the "Intuition Gadgets" chapter). Do not make the mistake of assuming it to be 
true. 
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This description of the inner workings of GT_GetlMsg() and GT_ReplylMsg() is provided for understanding only; 
it is crucial that the program make no assumptions or interpretations about the real IntuiMessage. Any such 
inferences are not likely to hold true in the future. See the section on documented side-effects for more 
information. 

IDCMP Flags 

The various GadTools gadget types require certain classes of IDCMP messages in order to work. Applications 
specify these IDCMP classes when the window is opened or later with ModifylDCMP() (see "Intuition Windows" 
chapter for more on this). Each kind of GadTools gadget requires one or more of these IDCMP classes: 



IDCMP_GADGETUP, IDCMP_GADGETDOWN, IDCMP_MOUSEMOVE, IDCMP_MOUSEBUTTONS and 
IDCMPJNTUITICKS. As a convenience, the IDCMP classes required by each kind of gadget are defined in 
<libraries/gadtools.h>. For example, SLIDERIDCMP is defined to be: 

ftdefine SLIDERIDCMP (IDCMP_GADGETUP | IDCMP_GADGETDOWN | IDCMP_MOUSEMOVE) 

Always OR the IDCMP Flag Bits. When specifying the IDCMP classes for a window, never 
add the flags together, always OR the bits together. Since many of the GadTools IDCMP 
constants have multiple bits set, adding the values will not lead to the proper flag combination. 

If a certain kind of GadTools gadget is used, the window must use all IDCMP classes required by that kind of 
gadget. Do not omit any that are given for that class, even if the application does require the message type. 

Because of the way GadTools gadgets are implemented, programs that use them always require notification 
about window refresh events. Even if the application performs no rendering of its own, it may not use the 
WFLG_NOCAREREFRESH window flag and must always set IDCMP_REFRESHWINDOW. See the section on 
"Gadget Refresh Functions" later in this chapter for more on this. 

Freeing Gadgets 

After closing the window, the gadgets allocated using CreateGadget() must be released. FreeGadgets() is a 
simple call that will free all the GadTools gadgets that it finds, beginning with the gadget whose pointer is passed 
as an argument. 

void FreeGadgets ( struct Gadget *gad ) ; 

The gad argument is a pointer to the first gadget to be freed. It is safe to call FreeGadgets() with a NULL gadget 
pointer, the function will then return immediately. Before calling FreeGadgets(), the application must first either 
remove the gadgets or close the window. 

When the gadget passed to FreeGadgetsQ is the first gadget in a linked list, the function frees all the GadTools 
gadgets on the list without patching pointers or trying to maintain the integrity of the list. Any non-GadTools 
gadgets found on the list will not be freed, hence the result will not necessarily form a nice list since any 
intervening GadTools gadgets will be gone. 

See the section on "Creating Gadget Lists" for more information on using linked lists of gadgets. 
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Simple GadTools Gadget Example 

The example listed here shows how to use the NewGadget structure and the GadTools libraries functions 
discussed above to create a simple button gadget. 

;/* simplegtgadget . c -- execute me to compile me 

lc -bl -cfistq -v -y simplegtgadget 

blink FROM LIBrc.o simplegtgadget . o TO simplegtgadget LIB LIB :1c. lib LIB :amiga. lib 

quit 

• * 

** The example listed here shows how to use the NewGadget structure and 
** the GadTools library functions discussed above to create a simple 
** button gadget. 

** Simple example of a GadTools gadget. Compiled with SAS C v5.10a 

*/ 

#define INTUI_V3 6_NAMES_0NLY 

#include <exec/types .h> 
#include <intuition/intuition.h> 
#include <intuition/gadgetclass . h> 
#include <libraries/gadtools . h> 

#include <clib/exec_protos . h> 
#include <clib/intuition_protos . h> 
#include <clib/gadtools_protos .h> 



#include <stdio.h> 

#ifdef LATTICE 

int CXBRK(void) { return(O); } /* Disable Lattice CTRL/C handling */ 

int chkabort (void) { return(O); } /* really */ 

#endif 

/* Gadget defines of our choosing, to be used as GadgetlD's. */ 
#define MYGAD_BUTTON (4) 

VOID process_window_events (struct Window *); 
VOID gadtoolsWindow (VOID) ; 

struct TextAttr Topaz80 = { " topaz . font " , 8, 0, 0, }; 

struct Library * IntuitionBase; 
struct Library *GadToolsBase; 

/* 

** Open all libraries and run. Clean up when finished or on error.. 

*/ 

void main (void) 

{ 

if ( (IntuitionBase = OpenLibrary ( "intuition. library" , 37)) != NULL ) 

{ 

if ( (GadToolsBase = OpenLibrary ( "gadtools . library" , 37)) != NULL ) 

{ 

gadtoolsWindow ( ) ; 

CloseLibrary (GadToolsBase) ; 

} 
CloseLibrary (IntuitionBase) ; 

} 
} 

/* 

** Prepare for using GadTools, set up gadgets and open window. 
** Clean up and when done or on error. 

*/ 

VOID gadtoolsWindow (VOID) 

{ 

struct Screen *mysc; 

struct Window *mywin; 

struct Gadget *glist, *gad; 

struct NewGadget ng; 

void *vi; 

glist = NULL; 

if ( (mysc = LockPubScreen (NULL) ) != NULL ) 

{ 

if ( (vi = GetVisualInfo(mysc, TAG_END) ) != NULL ) 

{ 

/* GadTools gadgets require this step to be taken */ 

gad = CreateContext (&glist) ; 

/* create a button gadget centered below the window title */ 

ng.ng_TextAttr = &Topaz80; 

ng.ng_VisualInf o = vi; 

ng.ng_Lef tEdge = 150; 

ng . ng_TopEdge = 20 + mysc->WBorTop + (mysc->Font->ta_YSize + 1) ; 

ng.ng_Width = 100; 

ng.ng__Height = 12; 

ng.ng_GadgetText = "Click Here"; 

ng.ng_GadgetID = MYGAD_BUTTON ; 

ng.ng_Flags = 0; 

gad = CreateGadget (BUTTON_KIND, gad, &ng, TAG_END) ; 

if (gad != NULL) 

{ 

if ( (mywin = OpenWindowTags (NULL, 

WA_Title, "GadTools Gadget Demo", 



} 



WA_Gadgets, glist, WA_AutoAdjust , TRUE, 
WA_Width, 400, WA_InnerHeight , 100, 
WA_DragBar, TRUE, WAJDepthGadget , TRUE, 
WA_Activate, TRUE, WA_CloseGadget , TRUE, 
WA_IDCMP, IDCMP_CLOSEWINDOW | 

IDCMP_REFRESHWINDOW | BUTTONIDCMP, 
WA_PubScreen, mysc, 
TAG_END) ) != NULL ) 

{ 

GT_Ref reshwindow (mywin, NULL) ; 

process_window_events (mywin) ; 

CloseWindow (mywin) ; 



/* FreeGadgets ( ) must be called after the context has been 
** created. It does nothing if glist is NULL 

*/ 

FreeGadgets (glist) ; 
FreeVisuallnf o (vi) ; 

} 
UnlockPubScreen (NULL, mysc); 

} 



/* 

** Standard message handling loop with GadTools message handling functions 
** used (GT_GetIMsg() and GT_ReplyIMsg ( ) ) . 

*/ 

VOID process_window_events (struct Window *mywin) 

{ 

struct IntuiMessage *imsg; 

struct Gadget *gad; 

BOOL terminated = FALSE; 

while (! terminated) 

{ 

Wait (1 << mywin- >UserPort - >mp_SigBit ) ; 

/* Use GT_GetIMsg() and GT_ReplyIMsg ( ) for handling */ 
/* IntuiMessages with GadTools gadgets. */ 

while ((! terminated) && (imsg = GT_GetIMsg (mywin- >UserPort) ) ) 

{ 

/* GT_ReplyIMsg ( ) at end of loop */ 

switch (imsg->Class) 

{ 

case IDCMP_GADGETUP : /* Buttons only report GADGETUP */ 

gad = (struct Gadget *) imsg->IAddress ; 

if (gad->GadgetID == MYGAD_BUTTON) 

printf ( "Button was pressed. \n" ) ; 

break; 
case IDCMP_CLOSEWINDOW: 

terminated = TRUE; 

break; 
case IDCMP_REFRESHWINDOW: 

/* This handling is REQUIRED with GadTools. */ 

GT_BeginRef resh (mywin) ; 

GT_EndRef resh (mywin, TRUE) ; 

break; 

} 
/* Use the toolkit message-replying function here... */ 
GT_ReplyIMsg (imsg) ; 
} 
} 
} 

Modifing Gadgets 

The attributes of a gadget are set up when the gadget is created. Some of these attributes can be changed later 
by using the GT_SetGadgetAttrs() function: 



void GT_SetGadgetAttrs (struct Gadget *gad, struct Window *win, 

struct Requester *req, Tag tagl, ... ) 

void GT_SetGadgetAttrsA( struct Gadget *gad, struct Window *win, 

struct Requester *req, struct Tagltem *taglist) 

The gad argument specifies the gadget to be changed while the win argument specifies the window the gadget is 
in. Currently, the req argument is unused and must be set to NULL. 

The gadget attributes are changed by passing tag arguments to these functions. The tag arguments can be either 
a set of Tagltems on the stack for GT_SetGadgetAttrs(), or a pointer to an array of Tagltems for 
GT_SetGadgetAttrsA(). The tag items specify the attributes that are to be changed for the gadget. Keep in 
mind though that not every gadget attribute can be modified this way. 

For example, in the slider gadget presented earlier, the level-formatting string may not be changed after the 
gadget is created. However, the slider's level may be changed to 5 as follows: 

GT_SetGadgetAttrs (slidergad, win, req, 
GTSL_Level, 5, 
TAG_END) ; 

Here are some other example uses of GT_SetGadgetAttrs() to change gadget attributes after it is created. 

/* Disable a button gadget */ 
GT_SetGadgetAttrs (buttongad, win, NULL, 

GA_Disabled, TRUE, 
TAG_END) ; 

/* Change a slider's range to be 1 to 100, currently at 50 */ 
GT_SetGadgetAttrs (slidergad, win, NULL, 

GTSL_Min, 1, 
GTSL_Max, 10 0, 
GTSL_Level, 50, 
TAG_END) ; 

/* Add a node to the head of listview's list, and make it the selected one */ 
GT_SetGadgetAttrs (listviewgad, win, NULL, 

/* detach list before modifying */ 

GTLV_Labels, ~0, 

TAG_END) ; 
AddHead (&lvlabels, knewnode) ; 
GT_SetGadgetAttrs (listviewgad, win, NULL, 

/* re-attach list */ 

GTLV_Labels, klvlabels, 

GTLV_Selected, 0, 

TAG_END) ; 
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When changing a gadget using these functions, the gadget will automatically update its visuals. No refresh is 
required, nor should any refresh call be performed. 

Warning: The GT_SetGadgetAttrs() functions may not be called inside of a 
GT_BeginRefresh()/GT_EndRefresh() pair. This is true of Intuition gadget functions 
generally, including those discussed in the "Intuition Gadgets" chapter. 

In the sections that follow all the possible attributes for each kind of gadget are discussed. The tags are also 
described in the Autodocs for GT_SetGadgetAttrs() in the Amiga ROM Kernel Reference Manual: Includes and 
Autodocs. 

Important. Tags that can only be sent to CreateGadget() and not to GT_SetGadgetAttrs() 
will be marked as create only in the discussion that follows. Those that are valid parameters 
to both functions will be marked as create and set. 



The Kinds of GadTools Gadgets 

This section discusses the unique features of each kind of gadget supported by the GadTools library. 

Button Gadgets 

Button gadgets (BUTTON_KIND) are perhaps the simplest kind of GadTools gadget. Button gadgets may be 
used for objects like the "OK" and "Cancel" buttons in requesters. GadTools will create a hit-select button with a 
raised bevelled border. The label supplied will be centered on the button's face. Since the label is not clipped, be 
sure that the gadget is large enough to contain the text supplied. 

Button gadgets recognize only one tag: 

GA_Disabled (BOOL) 

Set this attribute to TRUE to disable or ghost the button gadget, to FALSE otherwise. The default is 
FALSE. (Create and set.) 

When the user selects a button gadget, the program will receive an IDCMP_GADGETUP event. 

If clicking on a button causes a requester to appear, for example a button that brings up a color requester, then 
the button text should end in ellipsis (...), as in "Quit..." 

Text-Entry and Numeric-Entry Gadgets 

Text-entry (STRING_KIND) and number-entry (INTEGER_KIND) gadgets are fairly typical Intuition string gadgets. 
The typing area is contained by a border which is a raised ridge. 

Text-entry gadgets accept the following tags: 

GTST_String (STRPTR) 

A pointer to the string to be placed into the text-entry gadget buffer or NULL to get an empty text-entry 
gadget. The string itself is actually copied into the gadget's buffer. The default is NULL. (Create and 
set.) 
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GTST_MaxChars (UWORD) 

The maximum number of characters that the text-entry gadget should hold. The string buffer that gets 
created for the gadget will actually be one bigger than this number, in order to hold the trailing NULL. 
The default is 64. (Create only.) 

Number-entry gadgets accept the following tags: 

GTIN_Number (ULONG) 

The number to be placed into the number-entry gadget. The default is zero. (Create and set.) 

GTINJUaxChars (UWORD) 

The maximum number of digits that the number-entry gadget should hold. The string buffer that gets created for 

the gadget will actually be one bigger than this, in order to hold the trailing NULL. The default is 1 0. (Create only.) 

Both text-entry and number-entry gadgets, which are collectively called string gadgets, accept these common 
tags: 

STRINGAJustification 

This attribute controls the placement of the string or number within its box and can be one of 
GACT_STRINGLEFT, GACT_STRINGRIGHT or GACT_STRINGCENTER. The default is 
GACT_STRINGLEFT. (Create only.) 

STRINGA_ReplaceMode (BOOL) 

Set STRINGA_ReplaceMode to TRUE to get a string gadget which is in replace-mode, as opposed to 
auto-insert mode. (Create only.) 

GA_Disabled (BOOL) 



Set this attribute to TRUE to disable the string gadget, otherwise to FALSE. The default is FALSE. 
(Create and set.) 

STRINGA_ExitHelp (BOOL) 

(New for V37, ignored under V36). Set this attribute to TRUE if the application wants to hear the Help 
key from within this string gadget. This feature allows the program to hear the press of the Help key in 
all cases. If TRUE, pressing the help key while this gadget is active will terminate the gadget and send 
a message. The program will receive an IDCMP_GADGETUP message having a Code value of 
0x5F, the rawkey code for Help. Typically, the program will want to reactivate the gadget after 
performing the help-display. The default is FALSE. (Create only.) 

GA_TabCycle (BOOL) 

(New for V37, ignored under V36). If the user types Tab or Shift Tab into a GA_TabCycle gadget, 
Intuition will activate the next or previous such gadget in sequence. This gives the user easy keyboard 
control over which text-entry or number-entry gadget is active. Tab moves to the next GATabCycle 
gadget in the gadget list and Shift Tab moves to the previous one. When the user presses Tab or Shift 
Tab, Intuition will deactivate the gadget and send this program an IDCMP_GADGETUP message with 
the code field set to 0x09, the ASCII value for a tab. Intuition will then activate the next indicated 
gadget. Check the shift bits of the qualifier field to learn if Shift Tab was typed. The ordering of the 
gadgets may only be controlled by the order in which they were added to the window. For special 
cases, for example, if there is only one string gadget in the window, this feature can be suppressed by 
specifying the tagitem pair {GA_TabCycle, FALSE}. The default is TRUE. (Create only.) 
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GTST_EditHook (struct Hook *) 

(New for V37, ignored under V36). Pointer to a custom editing hook for this string or integer gadget. 
See the "Intuition Gadgets" chapter for more information on string gadget edit-hooks. 

As with all Intuition string gadgets, the program will receive an IDCMP_GADGETUP message only when the user 
presses Enter, Return, Help, Tab or Shift Tab while typing in the gadget. Note that, like Intuition string gadgets, 
the program will not hear anything if the user deactivates the string gadget by clicking elsewhere. Therefore, it is 
a good idea to always check the string gadget's buffer before using its contents, instead of just tracking its value 
as IDCMP_GADGETUP messages are received for this gadget. 

Be sure the code is designed so that nothing drastic happens, like closing a requester or opening a file, if the 
IDCMP_GADGETUP message has a non-zero Code field; the program will want to handle the Tab and Help 
cases intelligently. 

To read the string gadget's buffer, look at the Gadget's Stringlnfo Buffer: 

((struct Stringlnfo *) gad->SpecialInf o) ->Buf f er 

To determine the value of an integer gadget, look at the Gadget's Stringlnfo Longlnt in the same way. 

Always use the GTST_String or GTIN_Number tags to set these values. Never write to the Stringlnfo->Buffer or 
Stringlnfo->Longlnt fields directly. 

GadTools string and integer gadgets do not directly support the GAJmmediate property (which would cause 
Intuition to send an IDCMP_GADGETDOWN event when such a gadget is first selected). However, this property 
can be very important. Therefore, the following technique can be used to enable this property. 

Warning: Note that the technique shown here relies on directly setting flags in a GadTools 
gadget; this is not normally allowed since it hinders future compatibility. Do not attempt to 
change other flags or properties of GadTools gadgets except through the defined interfaces 
of CreateGadgetAQ and GT_SetGadgetAttrsA(). Directly modifying flags or properties is 
legal only when officially sanctioned by Commodore. 

To get the GAJmmediate property, pass the {GA_lmmediate,TRUE} tag to CreateGadgetA(). Even though this 
tag is ignored for string and integer gadgets under V37, this will allow future versions of GadTools to learn of your 
request in the correct way. Then, under V37 only, set the GACTJMMEDIATE flag in the gadget's Activation 
field: 



gad = CreateGadget ( STRING_KIND, gad, &ng, 
/* string gadget tags go here */ 
GTST_. . . , 

/* Add this tag for future GadTools releases */ 
GA_Immediate, TRUE, 

TAG_DONE ) ; 

if ( ( gad ) && ( GadToolsBase->lib_Version == 37) ) 

{ 

/* Under GadTools V37 only, set this attribute 

* directly. Do not set this attribute under 

* future versions of GadTools, or for gadgets 

* other than STRING_KIND or INTEGER_KIND . 

*/ 

gad->Activation |= GACT_IMMEDIATE ; 

} 
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Checkbox Gadgets 

Checkboxes (CHECKBOX_KIND) are appropriate for presenting options which may be turned on or off. This kind 
of gadget consists of a raised box which contains a checkmark if the option is selected or is blank if the option is 
not selected. Clicking on the box toggles the state of the checkbox. 

The width and height of a checkbox are currently fixed (to 26x1 1). If variable-sized checkboxes are added in the 
future, they will be done in a compatible manner. Currently the width and height specified in the NewGadget 
structure are ignored. 

The checkbox may be controlled with the following tags: 

GTCB_Checked (BOOL) 

Set this attribute to TRUE to set the gadget's state to checked. Set it to FALSE to mark the gadget as 
unchecked. The default is FALSE. (Create and set.) 

GA_Disabled (BOOL) 

Set this attribute to TRUE to disable the checkbox, to FALSE otherwise. The default is FALSE. 
(Create and set.) 

When the user selects a checkbox, the program will receive an IntuiMessage with a class of 
IDCMP_GADGETUP. As this gadget always toggles, the program can easily track the state of the gadget. Feel 
free to read the Gadget->Flags GFLG_SELECTED bit. Note, however, that the Gadget structure itself is not 
synchronized to the IntuiMessages received. If the user clicks a second time, the GFLG_SELECTED bit can 
toggle again before the program gets a chance to read it. This is true of any of the dynamic fields of the Gadget 
structure, and is worth being aware of, although only rarely will an application have to account for it. 

Mutually-Exclusive Gadgets 

Use mutually exclusive gadgets (MX_KIND), or radio buttons, when the user must choose only one option from a 
short list of possibilities. Mutually exclusive gadgets are appropriate when there are a small number of choices, 
perhaps eight or less. 

A set of mutually exclusive gadgets consists of a list of labels and beside each label, a small raised oval that looks 
like a button. Exactly one of the ovals is recessed and highlighted, to indicate the selected choice. The user can 
pick another choice by clicking on any of the raised ovals. This choice will become active and the previously 
selected choice will become inactive. That is, the selected oval will become recessed while the previous one will 
pop out, like the buttons on a car radio. 

Mutually exclusive gadgets recognize these tags: 

GTMX_Labels (STRPTR *) 

A NULL-pointer-terminated array of strings which are to be the labels beside each choice in the set of 



mutually exclusive gadgets. This array determines how many buttons are created. This array must be 
supplied to CreateGadget() and may not be changed. The strings themselves must remain valid for 
the lifetime of the gadget. (Create only.) 

GTMX_Active (UWORD) 

The ordinal number, counting from zero, of the active choice of the set of mutually exclusive gadgets. 
The default is zero. (Create and set.) 
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GTMX_Spacing (UWORD) 

The amount of space, in pixels, that will be placed between successive choices in a set of mutually 
exclusive gadgets. The default is one. (Create only.) 

When the user selects a new choice from a set of mutually exclusive gadgets, the program will receive an 
IDCMPGADGETDOWN IntuiMessage. Look in the IntuiMessage's Code field for the ordinal number of the 
new active selection. 

The ng_GadgetText field of the NewGadget structure is ignored for mutually exclusive gadgets. The text 
position specified in ng_Flags determines whether the item labels are placed to the left or the right of the radio 
buttons themselves. By default, the labels appear on the left. Do not specify PLACETEXT_ABOVE, 
PLACETEXT_BELOW or PLACETEXTJN for this kind of gadget. 

Like the checkbox, the size of the radio button is currently fixed, and the dimensions supplied in the NewGadget 
structure are ignored. If in the future the buttons are made scalable, it will be done in a compatible manner. 
Currently, mutually exclusive gadgets may not be disabled. 

Cycle Gadgets 

Like mutually exclusive gadgets, cycle gadgets (CYCLE_KIND) allow the user to choose exactly one option from 
among several. 

The cycle gadget appears as a raised rectangular button with a vertical divider near the left side. A circular arrow 
glyph appears to the left of the divider, while the current choice appears to the right. Clicking on the cycle gadget 
advances to the next choice, while shift-clicking on it changes it to the previous choice. 

Cycle gadgets are more compact than mutually exclusive gadgets, since only the current choice is displayed. 
They are preferable to mutually exclusive gadgets when a window needs to have several such gadgets as in the 
PrinterGfx Preferences editor, or when there is a medium number of choices. If the number of choices is much 
more than about a dozen, it may become too frustrating and inefficient for the user to find the desired choice. In 
that case, use a listview (scrolling list) instead. 

The tags recognized by cycle gadgets are: 

GTCY_Labels (STRPTR *) 

Like GTMX_Labels, this tag is associated with a NULL-pointer-terminated array of strings which are the 
choices that this gadget allows. This array must be supplied to CreateGadget(), and can only be 
changed starting in V37. The strings themselves must remain valid for the lifetime of the gadget. 
(Create only (V36), Create and set (V37).) 

GTCY_Active (UWORD) 

The ordinal number, counting from zero, of the active choice of the cycle gadget. The default is zero. 
(Create and set.) 

GA_Disabled (BOOL) 

(New for V37, ignored by V36.) Set this attribute to TRUE to disable the cycle gadget, to FALSE 
otherwise. The default is FALSE. (Create and set.) 
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When the user clicks or shift-clicks on a cycle gadget, the program will receive an IDCMP_GADGETUP 
IntuiMessage. Look in the Code field of the IntuiMessage for the ordinal number of the new active selection. 



Slider Gadgets 

Sliders are one of the two kinds of proportional gadgets offered by GadTools. Slider gadgets (SLIDER_KIND) are 
used to control an amount, a level or an intensity, such as volume or color. Scroller gadgets (SCROLLER_KIND) 
are discussed below. 

Slider gadgets accept the following tags: 

GTSL_Min (WORD) 

The minimum level of a slider. The default is zero. (Create and set.) 

GTSL_Max (WORD) 

The maximum level of a slider. The default is 15. (Create and set.) 

GTSL_Level (WORD) 

The current level of a slider. The default is zero. When the level is at its minimum, the knob will be all 
the way to the left for a horizontal slider or all the way at the bottom for a vertical slider. Conversely, the 
maximum level corresponds to the knob being to the extreme right or top. (Create and set.) 

GTSL_LevelFormat (STRPTR) 

The current level of the slider may be displayed in real-time alongside the gadget. To use the 
level-display feature, the program must be using a monospace font for this gadget. 

GTSL_LevelFormat specifies a printf()-style formatting string used to render the slider level beside 
the slider (the complete set of formatting options is described in the Exec library function 
RawDoFmt()). Be sure to use the T (long word) modifier for the number. Field-width specifiers may 
be used to ensure that the resulting string is always of constant width. The simplest would be "%2ld". 
A 2-digit hexadecimal slider might use "%02lx", which adds leading zeros to the number. Strings with 
extra text, such as "%3ld hours", are permissible. If this tag is specified, the program must also provide 
GTSLJVIaxLevelLen. By default, the level is not displayed. (Create only.) 

GTSL_MaxLevelLen (UWORD) 

The maximum length of the string that will result from the given level-formatting string. If this tag is 
specified, the program must also provide GTSL_LevelFormat. By default, the level is not displayed. 
(Create only.) 

GTSL_LevelPlace 

To choose where the optional display of the level is positioned. It must be one of PLACETEXT_LEFT, 
PLACETEXT_RIGHT, PLACETEXT_ABOVE or PLACETEXT_BELOW. The level may be placed 
anywhere with the following exception: the level and the label may not be both above or both below the 
gadget. To place them both on the same side, allow space in the gadget's label (see the example). 
The default is PLACETEXT_LEFT. (Create only.) 
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GTSL_DispFunc (LONG (*function)(struct Gadget *, WORD)) 

Optional function to convert the level for display. A slider to select the number of colors for a screen 
may operate in screen depth (1 to 5, for instance), but actually display the number of colors (2, 4, 8, 16 
or 32). This may be done by providing a GTSL_DispFunc function which returns 1 « level. The 
function must take a pointer to the Gadget as the first parameter and the level, a WORD, as the 
second and return the result as a LONG. The default behavior for displaying a level is to do so without 
any conversion. (Create only.) 

GAJmmediate (BOOL) 

Set this to TRUE to receive an IDCMPGADGETDOWN IntuiMessage when the user presses the 
mouse button over the slider. The default is FALSE. (Create only.) 

GA_RelVerify (BOOL) 

Set this to TRUE to receive an IDCMPGADGETUP IntuiMessage when the user releases the mouse 
button after using the slider. The default is FALSE. (Create only.) 

PGA Freedom 

Specifies which direction the knob may move. Set to LORIENT_VERT for a vertical slider or 
LORIENT_HORIZ for a horizontal slider. The default is LORIENT_HORIZ. (Create only.) 



GA_Disabled (BOOL) 

Set this attribute to TRUE to disable the slider, to FALSE otherwise. The default is FALSE. (Create and 
set.) 

Up to three different classes of IntuiMessage may be received at the port when the user plays with a slider, these 
are IDCMP_MOUSEMOVE, IDCMP_GADGETUP and IDCMP_GADGETDOWN. The program may examine the 
IntuiMessage Code field to discover the slider's level. 

IDCMPMOUSEMOVE IntuiMessages will be heard whenever the slider's level changes. 
IDCMP_MOUSEMOVE IntuiMessages will not be heard if the knob has not moved far enough for the level to 
actually change. For example if the slider runs from to 1 5 and is currently set to 1 2, if the user drags the slider 
all the way up the program will hear no more than three IDCMP_MOUSEMOVEs, one each for 13, 14 and 15. 

If {GA Immediate, TRUE} is specified, then the program will always hear an IDCMPGADGETDOWN 
IntuiMessage when the user begins to adjust a slider. If {GA_RelVerify, TRUE} is specified, then the program 
will always hear an IDCMP_GADGETUP IntuiMessage when the user finishes adjusting the slider. If 
IDCMP_GADGETUP or IDCMP_GADGETDOWN IntuiMessages are requested, the program will always hear 
them, even if the level has not changed since the previous IntuiMessage. 

Note that the Code field of the IntuiMessage structure is a UWORD, while the slider's level may be negative, 
since it is a WORD. Be sure to copy or cast the lntuiMessage->Code into a WORD if the slider has negative 
levels. 

If the user clicks in the container next to the knob, the slider level will increase or decrease by one. If the user 
drags the knob itself, then the knob will snap to the nearest integral position when it is released. 
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Here is an example of the screen-depth slider discussed earlier: 

/* NewGadget initialized here. Note the three spaces 

* after "Slider:", to allow a blank plus the two digits 

* of the level display 
*/ 

ng.ng_Flags = PLACETEXT_LEFT ; 
ng.ng_GadgetText = "Slider: " ; 

LONG DepthToColors (struct Gadget *gad, WORD level) 

{ 

return ( (WORD) (1 << level) ) ; 

} 

gad = CreateGadget (SLIDER_KIND, gad, &ng, 
GTSL_Min, 1, 
GTSL_Max, 5, 

GTSL_Level, current_depth, 
GTSL_MaxLevelLen, 2, 
GTSL_LevelFormat, "%21d", 
GTSL_DispFunc, DepthToColors, 
TAG_END) ; 

Scroller Gadgets 

Scrollers (SCROLLER_KIND) bear some similarity to sliders, but are used for a quite different job: they allow the 
user to adjust the position of a limited view into a larger area. For example, Workbench's windows have scrollers 
that allow the user to see icons that are outside the visible portion of a window. Another example is a scrolling list 
in a file requester which has a scroller that allows the user to see different parts of the whole list. 

A scroller consists of a proportional gadget and usually also has a pair of arrow buttons. 

While the slider deals in minimum, maximum and current level, the scroller understands Total, Visible and Top. 
For a scrolling list, Total would be the number of items in the entire list, Visible would be the number of lines 
visible in the display area and Top would be the number of the first line displayed in the visible part of the list. 



Top would run from zero to Total - Visible. For an area-scroller such as those in Workbench's windows, Total 
would be the height (or width) of the whole area, Visible would be the visible height (or width) and Top would be 
the top (or left) edge of the visible part. 

Note that the position of a scroller should always represent the position of the visible part of the project and never 
the position of a cursor or insertion point. 

Scrollers respect the following tags: 

GTSC_Top (WORD) 

The top line or position visible in the area that the scroller represents. The default is zero. (Create and 
set.) 

GTSCJTotal (WORD) 

The total number of lines or positions that the scroller represents. The default is zero. (Create and set.) 

GTSC_Visible (WORD) 

The visible number of lines or positions that the scroller represents. The default is two. (Create and 
set.) 
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GTSC_Arrows (UWORD) 

Asks for arrow gadgets to be attached to the scroller. The value supplied will be used as the width of 
each arrow button for a horizontal scroller or the height of each arrow button for a vertical scroller, the 
other dimension will be set by GadTools to match the scroller size. It is generally recommend that 
arrows be provided. The default is no arrows. (Create only.) 

GAJmmediate (BOOL) 

Set this to TRUE to receive an IDCMP_GADGETDOWN IntuiMessage when the user presses the 
mouse button over the scroller. The default is FALSE. (Create only.) 

GA_RelVerify (BOOL) 

Set this to TRUE to receive an IDCMPGADGETUP IntuiMessage when the user releases the mouse 
button after using the scroller. The default is FALSE. (Create only.) 

PGAFreedom 

Specifies which direction the knob may move. Set to LORIENT_VERT for a vertical scroller or 
LORIENT_HORIZ for a horizontal scroller. The default is LORIENTJHORIZ. (Create only.) 

GA_Disabled (BOOL) 

Set this attribute to TRUE to disable the scroller, to FALSE otherwise. The default is FALSE. (Create 
and set.) 

The IntuiMessages received for a scroller gadget are the same in nature as those for a slider defined above, 
including the fact that messages are only heard by the program when the knob moves far enough for the Top 
value to actually change. The Code field of the IntuiMessage will contain the new Top value of the scroller. 

If the user clicks on an arrow gadget, the scroller moves by one unit. If the user holds the button down over an 
arrow gadget, it repeats. 

If the user clicks in the container next to the knob, the scroller will move by one page, which is the visible amount 
less one. This means that when the user pages through a scrolling list, any pair of successive views will overlap 
by one line. This helps the user understand the continuity of the list. If the program is using a scroller to pan 
through an area then there will be an overlap of one unit between successive views. It is recommended that Top, 
Visible and Total be scaled so that one unit represents about five to ten percent of the visible amount. 

Listview Gadgets 

Listview gadgets (LISTVIEW_KIND) are scrolling lists. They consist of a scroller with arrows, an area where the 
list itself is visible and optionally a place where the current selection is displayed, which may be editable. The 
user can browse through the list using the scroller or its arrows and may select an entry by clicking on that item. 

There are a number of tags that are used with listviews: 



GTLV_Labels (struct List *) 

An Exec list whose nodes' ln_Name fields are to be displayed as items in the scrolling list. If the list is 
empty, an empty List structure or a NULL value may be used for GTLV_Labels. This tag accepts a 
value of "~0" to detach the list from the listview, defined below. The default is NULL. (Create and set.) 
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GTLV_Top (UWORD) 

The ordinal number of the top item visible in the listview. The default is zero. (Create and set.) 

GTLV_ReadOnly (BOOL) 

Set this to TRUE for a read-only listview, which the user can browse, but not select items from. A 
read-only listview can be recognized because the list area is recessed, not raised. The default is 
FALSE. (Create only.) 

GTLV_ScrollWidth (UWORD) 

The width of the scroller to be used in the listview. Any value specified must be reasonably bigger than 
zero. The default is 16. (Create only.) 

GTLV_ShowSelected (struct Gadget *) 

Use this tag to show the currently selected entry displayed underneath the listview. Set its value to 
NULL to get a read-only (TEXT_KIND) display of the currently selected entry or set it to a pointer to an 
already-created GadTools STRING_KIND gadget to allow the user to directly edit the current entry. By 
default, there is no display of the currently selected entry. (Create only.) 

GTLV_Selected (UWORD) 

Ordinal number of the item to be placed into the display of the current selection under the listview. This 
tag is ignored if GTLV_ShowSelected is not used. Set it to "~0" to have no current selection. The 
default is "~0". (Create and set.) 

LAYOUTA_Spacing (UWORD) 

Extra space, in pixels, to be placed between the entries in the listview. The default is zero. (Create 
only.) 

The program will only hear from a listview when the user selects an item from the list. The program will then 
receive an IDCMP_GADGETUP IntuiMessage. This message will contain the ordinal number of the item within 
the list that was selected in the Code field of the message. This number is independent of the displayed listview, 
it is the offset from the start of the list of items. 

If the program attaches a display gadget by using the Tagltem {GTLV ShowSelected, NULL}, then whenever 
the user clicks on an entry in the listview it will be copied into the display gadget. 

If the display gadget is to be editable, then the program must first create a GadTools STRING_KIND gadget 
whose width matches the width of the listview. The Tagltem {GTLV_ShowSelected, stringgad} is used to 
install the editable gadget, where stringgad is the pointer returned by CreateGadget(). When the user selects 
any entry from the listview, it gets copied into the string gadget. The user can edit the string and the program will 
hear normal string gadget IDCMP_GADGETUP messages from the STRING_KIND gadget. 

The Exec List and its Node structures may not be modified while they are attached to the listview, since the list 
might be needed at any time. If the program has prepared an entire new list, including a new List structure and all 
new nodes, it may replace the currently displayed list in a single step by calling GT_SetGadgetAttrs() with the 
Tagltem {GTLV_Labels, newlist}. If the program needs to operate on the list that has already been passed to 
the listview, it should detach the list by setting the GTLV_Labels attribute to "~0". When done modifying the list, 
resubmit it by setting GTLVLabels to once again point to it. This is better than first setting the labels to NULL 
and later back to the list, since setting GTLV_Labels to NULL will visually clear the listview. If the GTLV_Labels 
attribute is set to "~0", the program is expected to set it back to something determinate, either a list or NULL, soon 
after. 
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The height specified for the listview will determine the number of lines in the list area. When creating a listview, it 
will be no bigger than the size specified in the NewGadget structure. The size will include the current-display 
gadget, if any, that has been requested via the GTLV_ShowSelected tag. The listview may end up being less tall 



than the application asked for, since the calculated height assumes an integral number of lines in the list area. 

By default, the gadget label will be placed above the listview. This may be overridden using ng_Flags. 

Currently, a listview may not be disabled. 

Palette Gadgets 

Palette gadgets (PALETTE_KIND) let the user pick a color from a set of several. A palette gadget consists of a 
number of colored squares, one for each color available. There may also be an optional indicator square which is 
filled with the currently selected color. To create a color editor, a palette gadget would be combined with some 
sliders to control red, green and blue components, for example. 

Palette gadgets use the following tags: 

GTPA_Depth (UWORD) 

The number of bitplanes that the palette represents. There will be 1 « depth squares in the palette 
gadget. The default is one. (Create only.) 

GTPA_Color (UBYTE) 

The selected color of the palette. The default is one. (Create and set.) 

GTPA_ColorOffset (UBYTE) 

The first color to use in the palette. For example, if GTPA Depth is two and GTPA_ColorOffset is 
four, then the palette will have squares for colors four, five, six and seven. The default is zero. (Create 
only.) 

GTPAJndicatorWidth (UWORD) 

The desired width of the current-color indicator. By specifying this tag, the application is asking for an 
indicator to be placed to the left of the color selection squares. The indicator will be as tall as the 
gadget itself. By default there is no indicator. (Create only.) 

GTPAJndicatorHeight (UWORD) 

The desired height of the current-color indicator. By specifying this tag, the application is asking for an 
indicator to be placed above the color selection squares. The indicator will be as wide as the gadget 
itself. By default there is no indicator. (Create only.) 

GA_Disabled (BOOL) 

Set this attribute to TRUE to disable the palette gadget, to FALSE otherwise. The default is FALSE. 
(Create and set.) 

An IDCMP_GADGETUP IntuiMessage will be received when the user selects a color from the palette. The 
current-color indicator is recessed, indicating that clicking on it has no effect. 

If the palette is wide and not tall, use the GTPAJndicatorWidth tag to put the indicator on the left. If the palette 
is tall and narrow, put the indicator on top using GTPAJndicatorHeight. 
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By default, the gadget's label will go above the palette gadget, unless GTPAJndicatorWidth is specified, in 
which case the label will go on the left. In either case, the default may be overridden by setting the appropriate 
flag in the NewGadget's ngj r lags field. 

The size specified for the palette gadget will determine how the area is subdivided to make the individual color 
squares. The actual size of the palette gadget will be no bigger than the size given, but it can be smaller in order 
to make the color squares all exactly the same size. 

Text-Display and Numeric-Display Gadgets 

Text-display (TEXTJ<IND) and numeric-display (NUMBERJ<IND) gadgets are read-only displays of information. 
They are useful for displaying information that is not editable or selectable, while allowing the application to use 
the GadTools formatting and visuals. Conveniently, the visuals are automatically refreshed through normal 
GadTools gadget processing. The values displayed may be modified by the program in the same way other 
GadTools gadgets may be updated. 



Text-display and number-display gadgets consist of a fixed label (the one supplied as the NewGadget's 
ng_GadgetText), as well as a changeable string or number (GTTX_Text or GTNM_Number respectively). The 
fixed label is placed according to the PLACETEXT_ flag chosen in the NewGadget ng_Flags field. The variable 
part is aligned to the left-edge of the gadget. 

Text-display gadgets recognize the following tags: 

GTTX_Text (STRPTR) 

Pointer to the string to be displayed or NULL for no string. The default is NULL. (Create and set.) 

GTTX_Border (BOOL) 

Set to TRUE to place a recessed border around the displayed string. The default is FALSE. (Create 
only.) 

GTTX_CopyText (BOOL) 

This flag instructs the text-display gadget to copy the supplied GTTX_Text string instead of using only 
a pointer to the string. This only works for the value of GTTXText set at CreateGadgetQ time. If 
GTTX_Text is changed, the new text will be referenced by pointer, not copied. Do not use this tag 
without a non-NULL GTTX_Text. (Create only.) 

Number-display gadgets have the following tags: 

GTNM_Number (LONG) 

The number to be displayed. The default is zero. (Create or set.) 

GTNM_Border (BOOL) 

Set to TRUE to place a recessed border around the displayed number. The default is FALSE. (Create 
only.) 

Since they are not selectable, text-display and numeric-display gadgets never cause IntuiMessages to be sent to 
the application. 
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Generic Gadgets 

If the application requires a specialized gadget which does not fit into any of the defined GadTools kinds but 
would still like to use the GadTools gadget creation and deletion functions, it may create a GadTools generic 
gadget and use it any way it sees fit. In fact, all of the kinds of GadTools gadgets are created out of GadTools 
GENERIC_KIND gadgets. 

The gadget that gets created will heed almost all the information contained in the NewGadget structure supplied. 

If ng_GadgetText is supplied, the Gadget's GadgetText will point to an IntuiText structure with the provided 
string and font. However, do not specify any of the PLACETEXT ng_Flags, as they are currently ignored by 
GENERIC_KIND gadgets. PLACETEXT flags may be supported by generic GadTools gadgets in the future. 

It is up to the program to set the Flags, Activation, GadgetRender, SelectRender, MutualExclude and 
Speciallnfo fields of the Gadget structure. 

The application must also set the GadgetType field, but be certain to preserve the bits set by CreateGadget(). 
For instance, to make a gadget boolean, use: 

gad->GadgetType |= GTYP_BOOLGADGET ; 
and not 

gad->GadgetType = GTYP_BOOLGADGET ; 

Using direct assignment, (the = operator), clears all other flags in the GadgetType field and the gadget may not 
be properly freed by FreeGadgetsQ. 



Functions For Setting Up GadTools Menus and Gadgets 

This section gives all the details on the functions used to set up GadTools menus and gadgets that were 
mentioned briefly earlier in this chapter. 

GetVisuallnfoQ and FreeVisuallnfoQ 

In order to ensure their best appearance, GadTools gadgets and menus need information about the screen on 
which they will appear. Before creating any GadTools gadgets or menus, the program must get this information 
using the GetVisuallnfo() call. 

APTR GetVisuallnf oA ( struct Screen *screen, struct Tagltem *taglist ) ; 
APTR GetVisuallnf o ( struct Screen *screen, Tag tagl, ... ) ; 

Set the screen argument to a pointer to the screen you are using. The tag arguments, tagl or taglist, are 
reserved for future extensions. Currently none are recognized, so only TAG_END should be used. 

The function returns an abstract handle called the Visuallnfo. For GadTools gadgets, the ng_Visuallnfo field of 
the NewGadget structure must be set to this handle before the gadget can be added to the window. GadTools 
menu layout and creation functions also require the Visuallnfo handle as an argument. 
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There are several ways to get the pointer to the screen on which the window will be opened. If the application has 
its own custom screen, this pointer is known from the call to OpenScreenQ or OpenScreenTagsQ. If the 
application already has its window opened on the Workbench or some other public screen, the screen pointer can 
be found in Window.WScreen. Often the program will create its gadgets and menus before opening the window. 
In this case, use LockPubScreen() to get a pointer to the desired public screen, which also provides a lock on the 
screen to prevent it from closing. See the chapters "Intuition Screens" and "Intuition Windows" for more about 
public screens. 

The Visuallnfo data must be freed after all the gadgets and menus have been freed but before releasing the 
screen. Custom screens are released by calling CloseScreenQ, public screens are released by calling 
CloseWindowQ or UnlockPubScreenQ, depending on the technique used. Use FreeVisuallnfo() to free the 
visual info data. 

void FreeVisuallnfo ( APTR vi ); 

This function takes just one argument, the Visuallnfo handle as returned by GetVisuallnfoQ. The sequence of 
events for using the Visuallnfo handle could look like this: 

initO 

{ 

myscreen = LockPubScreen (NULL) ; 

if ( imyscreen) 

{ 

cleanup ( "Failed to lock default public screen"); 

} 
vi = GetVisuallnf o (myscreen) ; 
if (!vi) 

{ 

cleanup ( "Failed to GetVisuallnf o" ) ; 

} 
/* Create gadgets here */ 
ng.ng_VisualInf o = vi; 

}" 

void cleanup (STRPTR errorstr) 

{ 

/* These functions may be safely called with a NULL parameter: */ 

FreeGadgets (glist) ; 

FreeVisuallnfo (vi) ; 



if (myscreen) 

UnlockPubScreen (NULL, myscreen) ; 

printf (errorstr) ; 

} 

CreateContext() 

Use of GadTools gadgets requires some per-window context information. CreateContext() establishes a place for 
that information to go. This function must be called before any GadTools gadgets are created. 

struct Gadget *CreateContext ( struct Gadget **glistptr ) ; 

The glistptr argument is a double-pointer to a Gadget structure. More specifically, this is a pointer to a 
NULL-initialized pointer to a Gadget structure. 

The return value of CreateContextQ is a pointer to this gadget, which should be fed to the program's first call to 
CreateGadgetQ. This pointer to the Gadget structure returned by CreateContext(), may then serve as a handle 
to the list of gadgets as they are created. The code fragment listed in the next section shows how to use 
CreateContext() together with CreateGadget() to make a linked list of GadTools gadgets. 
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Creating Gadget Lists 

In the discussion of CreateGadgetQ presented earlier, the examples showed only how to make a single gadget. 
For most applications that use GadTools, however, a whole list of gadgets will be needed. To do this, the 
application could use code such as this: 

struct NewGadget *newgadl, *newgad2, *newgad3 ; 
struct Gadget *glist = NULL; 
struct Gadget *pgad; 

/* Initialize NewGadget structures */ 

/* Note that CreateContext () requires a POINTER to a NULL-initialized 

* pointer to struct Gadget : 

*/ 

pgad = CreateContext (&glist) ; 

pgad = CreateGadget (BUTTON_KIND, pgad, newgadl , TAG_END) 
pgad = CreateGadget (STRING_KIND, pgad, newgad2 , TAG_END) 
pgad = CreateGadget (MX_KIND, pgad, newgad3 , TAG_END) 

if ( !pgad) 

{ 

FreeGadgets (glist) ; 

exit_error ( ) ; 

} 
else 

{ 

if ( mywin=OpenWindowTags (NULL, 

WA_Gadgets, glist, 

/* Other tags. . . */ 

TAG_END) ) 

{ 

/* Complete the rendering of the gadgets */ 
GT_RefreshWindow(win, NULL) ; 

/* and continue on. . . */ 



CloseWindow (mywin) ; 
} 

FreeGadgets (glist) ; 
} 

The pointer to the previous gadget, pgad in the code fragment above, is used for three purposes. First, when 
CreateGadgetQ is called multiple times, each new gadget is automatically linked to the previous gadget's 
NextGadget field, thus creating a gadget list. Second, if one of the gadget creations fails (usually due to low 
memory, but other causes are possible), then for the next call to CreateGadget(), pgad will be NULL and 
CreateGadgetQ will fail immediately. This means that the program can perform several successive calls to 
CreateGadgetQ and only have to check for failure at the end. 

Finally, although this information is hidden in the implementation and not important to the application, certain calls 
to CreateGadget() actually cause several Intuition gadgets to be allocated and these are automatically linked 
together without program interaction, but only if a previous gadget pointer is supplied. If several gadgets are 
created by a single CreateGadgetQ call, they work together to provide the functionality of a single GadTools 
gadget. The application should always act as though the gadget pointer returned by CreateGadget() points to a 
single gadget instance. See "Documented Side-Effects" for a warning. 

There is one exception to the fact that a program only has to check for failure after the last CreateGadgetQ call 
and that is when the application depends on the successful creation of a gadget and caches or immediately uses 
the gadget pointer returned by CreateGadgetQ. 
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For instance, if the program wants to create a string gadget and save a pointer to the string buffer, it might do so 
as follows: 

gad = CreateGadget (STRING_KIND, gad, &ng, 

GTST_String, "Hello World" , 
TAG_END) ; 
if (gad) 

{ 

stringbuffer = ((struct Stringlnfo *) (gad->SpecialInf o) ) ->Buf f er; 

} 

/* Creation can continue here: */ 
gad = CreateGadget (.. ._KIND, gad, &ng2 , 

TAG_END) ; 

A major benefit of having a reusable NewGadget structure is that often many fields do not change and some 
fields change incrementally. For example, the application can set just the NewGadget's ng Visuallnfo and 
ng_TextAttr only once and never have to modify them again even if the structure is reused to create many 
gadgets. A set of similar gadgets may share size and some positional information so that code such as the 
following might be used: 

/* Assume that the NewGadget structure 'ng' is fully 
* initialized here for a button labelled "OK" 
*/ 
gad = CreateGadget (BUTTON_KIND, gad, &ng, 
TAG_END) ; 

/* Modify only those fields that need to change: */ 
ng . ng_Gadget ID++ ; 
ng.ng_Lef tEdge += 8 0; 
ng .ng_GadgetText = "Cancel"; 
gad = CreateGadget (BUTTON_KIND, gad, &ng, TAG_END) ; 

Warning: All gadgets created by GadTools currently have the GADTOOL_TYPE bit set in their 
GadgetType field. It is not correct to check for, set, clear or otherwise rely on this since it is 
subject to change. 



Gadget Refresh Functions 

Normally, GadTools gadgets are created and then attached to a window when the window is opened, either 
through the WA_Gadget tag or the NewWindow.FirstGadget field. Alternately, they may be added to a window 
after it is open by using the functions AddGListQ and RefreshGList(). 

Regardless of which way gadgets are attached to a window, the program must then call the 
GT_RefreshWindow() function to complete the rendering of GadTools gadgets. This function takes two 
arguments. 

void GT_Ref reshWindow ( struct Window *win, struct Requester *req ) ; 

This win argument is a pointer to the window that contains the GadTools gadgets. The req argument is currently 
unused and should be set to NULL. This function should only be called immediately after adding GadTools 
gadgets to a window. Subsequent changes to GadTools gadget imagery made through calls to 
GT_SetGadgetAttrs() will be automatically performed by GadTools when the changes are made. (There is no 
need to call GT_RefreshWindow() in that case.) 
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As mentioned earlier, applications must always ask for notification of window refresh events for any window that 
uses GadTools gadgets. When the application receives an IDCMP_REFRESHWINDOW message for a window, 
Intuition has already refreshed its gadgets. Normally, a program would then call Intuition's BeginRefresh(), 
perform its own custom rendering operations, and finally call EndRefresh(). But for a window that uses GadTools 
gadgets, the application must call GT_BeginRefresh() and GT_EndRefresh() in place of BeginRefreshQ and 
EndRefreshQ. This allows the the GadTools gadgets to be fully refreshed. 

void GT_BeginRef resh ( struct Window *win ); 

void GT_EndRef resh ( struct Window *win, long complete ) ; 

For both functions, the win argument is a pointer to the window to be refreshed. For GT_EndRefresh(), set the 
complete argument to TRUE if refreshing is complete, set it to FALSE otherwise. See the discussion of 
BeginRefresh() and EndRefresh() in the "Intuition Windows" chapter for more about window refreshing. 

When using GadTools gadgets, the program may not set the window's WFLG_NOCAREREFRESH flag. Even if 
there is no custom rendering to be performed, GadTools gadgets requires this minimum code to handle 
IDCMP_REFRESHWINDOW messages: 

case IDCMP_REFRESHWINDOW: 
GT_BeginRef resh (win) ; 

/* custom rendering, if any, goes here */ 
GT_EndRef resh (win, TRUE) ; 
break ; 

Other GadTools Functions 

This section discusses some additional support functions in the GadTools library that serve special needs. 

GT_FilterlMsg() and GT_PostFilterlMsg() 

For most GadTools programs, GT_GetlMsg() and GT_ReplylMsg() work perfectly well. In rare cases an 
application may find they pose a bit of a problem. A typical case is when all messages are supposed to go 
through a centralized ReplyMsgQ that cannot be converted to a GT_ReplylMsg(). Since calls to GT_GetlMsg() 
and GT_ReplylMsg() must be paired, there would be a problem. 

For such cases, the GT_FilterlMsg() and GT_PostFilterlMsg() functions are available. These functions allow 
GetMsg() and ReplyMsg() to be used in a way that is compatible with GadTools. 

Warning: These functions are for specialized use only and will not be used by the majority of 
applications. See GT_GetlMsg() and GT_ReplylMsg() for standard message handling. 

struct IntuiMessage *GT_FilterIMsg ( struct IntuiMessage *imsg ) ; 
struct IntuiMessage *GT_PostFilterIMsg ( struct IntuiMessage *imsg ) ; 



The GT_FilterlMsg() function should be called right after GetMsg(). It takes a pointer to the original 
IntuiMessage and, if the message applies to a GadTools gadget, returns either a modified IntuiMessage or a 
NULL. A NULL return signifies that the message was consumed by a GadTools gadget (and not needed by the 
application). 
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The GT_PostFilterlMsg() function should be called before replying to any message modified by GT_FilterlMsg(). 
It takes a pointer to the modified version of an IntuiMessage obtained with GT_FilterlMsg() and returns a pointer 
to the original IntuiMessage. 

The typical calling sequence for a program that uses these functions, is to call GetMsg() to get the IntuiMessage. 
Then, if the message applies to a window which contains GadTools gadgets, call GT_FilterlMsg(). Any message 
returned by GT_FilterlMsg() should be used like a message returned from GT_GetlMsg(). 

When done with the message, the application must call GT_PostFilterlMsg() to perform any clean up 
necessitated by the previous call to GT_FilterlMsg(). In all cases, the application must then reply the original 
IntuiMessage using ReplyMsg(). This is true even for consumed messages as these are not replied by 
GadTools. For example, the application could use code such as this: 

/* port is a message port receiving different messages */ 
/* gtwindow is the window that contains GadTools gadgets */ 

imsg = GetMsg (port) ; 

/* Is this the window with GadTools gadgets? */ 
if (imsg->IDCMPWindow == gtwindow) 

{ 

/* Filter the message and see if action is needed */ 

if (gtimsg = GT_FilterIMsg (imsg) ) 

{ 

switch (gtimsg->Class) 

{ 
/* Act depending on the message */ 

}" 

/* Clean up the filtered message. The return value is not */ 

/* needed since we already have a pointer to the original */ 

/* message. */ 

GT_PostFilterIMsg (gtimsg) ; 

} 
} 
/* other stuff can go here */ 
ReplyMsg (imsg) ; 

You should not make any assumptions about the contents of the unfiltered IntuiMessage (imsg in the above 
example). Only two things are guaranteed: the unfiltered IntuiMessage must be replied to and the unfiltered 
IntuiMessage (if it produces anything when passed through GT_FilterlMsg()) will produce a meaningful 
GadTools IntuiMessage like those described in the section on the different kinds of gadgets. The relationship 
between the unfiltered and filtered messages are expected to change in the future. See the section on 
documented side-effects for more information. 

DrawBevelBox() 

A key visual signature shared by most GadTools gadgets is the raised or recessed bevelled box imagery. Since 
the program may wish to create its own boxes to match, GadTools provides the DrawBevelBox() and 
DrawBevelBoxA() functions. 

void DrawBevelBoxA ( struct RastPort *rport, long left, long top, 

long width, long height, struct Tagltem *taglist ) ; 

void DrawBevelBox ( struct RastPort *rport, long left, long top, 

long width, long height, Tag tagl, ... ) ; 



The rport argument is a pointer to the RastPort into which the box is to be rendered. The left, top, width and 
height arguments specify the dimensions of the desired box. 
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The tag arguments, tagl or taglist, may be set as follows: 

GT_Visuallnfo (APTR) 

The Visuallnfo handle as returned by a prior call to GetVisuallnfo(). This value is required. 

GTBB_Recessed (BOOL) 

A bevelled box may either appear to be raised to signify an area of the window that is selectable or 
recessed to signify an area of the window in which clicking will have no effect. Set this boolean tag 
to TRUE to get a recessed box. Omit this tag entirely to get a raised box. 

DrawBevelBoxQ is a rendering operation, not a gadget. This means that the program must refresh any bevelled 
boxes rendered through this function if the window gets damaged. 

Gadget Keyboard Equivalents 

Often, users find it convenient to control gadgets using the keyboard. Starting with V37, it is possible to denote the 
keyboard equivalent for a GadTools gadget. The keyboard equivalent will be an underscored character in the 
gadget label, for easy identification. At the present time, however, the application is still responsible for 
implementing the reaction to each keypress. 

Denoting a Gadget's Keyboard Equivalent 

In order to denote the key equivalent, the application may add a marker-symbol to the gadget label. This is done 
by placing the marker-symbol immediately before the character to be underscored. This symbol can be any 
character that is not used in the label. The underscore character, '_' is the recommended marker-symbol. So, for 
example, to mark the letter "F" as the keyboard equivalent for a button labelled "Select Font...", create the gadget 
text: 

ng . ng_GadgetText = "Select _Font . . . " ; 

To inform GadTools of the underscore in the label, pass the GAUnderscore tag to CreateGadgetQ or 
CreateGadgetAQ. The data-value associated with this tag is a character, not a string, which is the 
marker-symbol used in the gadget label: 

GAJJnderscore, '_',/* Note '_', not "_" !!! */ 

GadTools will create a gadget label which consists of the text supplied with the marker-symbol removed and the 
character following the marker-symbol underscored. 

The gadget's label would look something like: 

Select Font . . . 



Implementing a Gadget's Keyboard Equivalent Behaviour 

Currently, GadTools does not process keyboard equivalents for gadgets. It is up to the application writer to 
implement the correct behavior, normally by calling GT_SetGadgetAttrs() on the appropriate gadget. For some 
kinds of gadget, the behavior should be the same regardless of whether the keyboard equivalent was pressed 
with or without the shift key. For other gadgets, shifted and unshifted keystrokes will have different, usually 
opposite, effects. 
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Here is the correct behavior for keyboard equivalents for each kind of GadTools gadget: 

Button Gadgets 

The keyboard equivalent should invoke the same function that clicking on the gadget does. There is 
currently no way to highlight the button visuals programmatically when accessing the button through a 



keyboard equivalent. 

Text-Entry and Number-Entry Gadgets 

The keyboard equivalent should activate the gadget so the user may type into it. Use Intuition's 
ActivateGadget() call. 

Checkbox Gadgets 

The keyboard equivalent should toggle the state of the checkbox. Use GT_SetGadgetAttrs() and the 
GTCB_Checked tag. 

Mutually-Exclusive Gadgets 

The unshifted keystroke should activate the next choice, wrapping around from the last to the first. The 
shifted keystroke should activate the previous choice, wrapping around from the first to the last. Use 
GT_SetGadgetAttrs() and the GTMX_Active tag. 

Cycle Gadgets 

The unshifted keystroke should activate the next choice, wrapping around from the last to the first. The 
shifted keystroke should activate the previous choice, wrapping around from the first to the last. Use 
GT_SetGadgetAttrs() and the GTCY_Active tag. 

Slider Gadgets 

The unshifted keystroke should increase the slider's level by one, stopping at the maximum, while the 
shifted keystroke should decrease the level by one, stopping at the minimum. Use 
GT_SetGadgetAttrs() and the GTSL_Level tag. 

Scroller Gadgets 

The unshifted keystroke should increase the scroller's top by one, stopping at the maximum, while the 
shifted keystroke should decrease the scroller's top by one, stopping at the minimum. Use 
GT_SetGadgetAttrs() and the GTSC_Top tag. 

Listview Gadgets 

The unshifted keystroke should cause the next entry in the list to become the selected one, stopping at 
the last entry, while the shifted keystroke should cause the previous entry in the list to become the 
selected one, stopping at the first entry. Use GT_SetGadgetAttrs() and the GTLVTop and 
GTLV_Selected tags. 

Palette Gadgets 

The unshifted keystroke should select the next color, wrapping around from the last to the first. The 
shifted keystroke should activate the previous color, wrapping around from the first to the last. Use 
GT_SetGadgetAttrs() and the GTPA_Color tag. 

Text-Display and Number-Display Gadgets 

These kinds of GadTools gadget have no keyboard equivalents since they are not selectable. 

Generic Gadgets 

Define appropriate keyboard functions based on the kinds of keyboard behavior defined for other 
GadTools kinds. 
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Complete GadTools Gadget Example 

Here's a working example showing how to set up and use a linked list of GadTools gadgets complete with 
keyboard shortcuts. 

/* gadtoolsgadgets . c 

** Simple example of using a number of gadtools gadgets. 

** Here's a working example showing how to set up and use a linked list 
** of GadTools gadgets complete with keyboard shortcuts. 

** Compiled with SAS C v5.10a 

** lc -bl -cfistq -v -y gadtoolsgadgets 

** blink FROM LIB:c.o gadtoolsgadgets . o TO gadtoolsgadgets LIB LIB:lc.lib LIB:amiga. lib 

*/ 



#define INTUI_V3 6_NAMES_ONLY 

#include <exec/types . h> 
#include <intuition/intuition.h> 
#include <intuition/gadgetclass .h> 
#include <libraries/gadtools . h> 

#include <clib/exec_protos . h> 
#include <clib/graphics_protos . h> 
#include <clib/intuition_protos . h> 
#include <clib/gadtools_protos . h> 

#include <stdio.h> 

#ifdef LATTICE 

int CXBRK(void) { return(O); } /* Disable Lattice CTRL/C handling */ 

int chkabort (void) { return(O); } /* really */ 

#endif 

/* Gadget defines of our choosing, to be used as Gadget ID'S, 
** also used as the index into the gadget array my_gads[] . 

*/ 

#define MYGAD_SLIDER (0) 

#define MYGAD_STRING1 (1) 

#define MYGAD_STRING2 (2) 

#define MYGAD_STRING3 (3) 

#define MYGAD_BUTTON (4) 

/* Range for the slider: */ 
#define SLIDER_MIN (1) 
#define SLIDER_MAX (20) 

struct TextAttr Topaz80 = { "topaz . font " , 8, 0, 0, }; 

struct Library *IntuitionBase; 
struct Library *Gf xBase; 
struct Library *GadToolsBase; 

/* Print any error message. We could do more fancy handling (like 
** an EasyRequest ( ) ) , but this is only a demo. 

*/ 

void errorMessage (STRPTR error) 

{ 

if (error) 

printf ( "Error : %s\n", error); 



/* 

** Function to handle a GADGETUP or GADGETDOWN event. For GadTools gadgets, 
** it is possible to use this function to handle MOUSEMOVEs as well, with 
** little or no work. 

*/ 

VOID handleGadgetEvent (struct Window *win, struct Gadget *gad, UWORD code, 
WORD *slider_level , struct Gadget *my_gads[]) 

{ 

switch (gad->GadgetID) 

{ 

case MYGAD_SLIDER: 

/* Sliders report their level in the IntuiMessage Code field: */ 

printf ( "Slider at level %ld\n", code); 

*slider_level = code; 

break; 
case MYGAD_STRING1 : 

/* String gadgets report GADGETUP' s */ 

printf ( "String gadget 1: '%s'.\n", 

((struct Stringlnfo *) gad->SpecialInf o) ->Buf f er) ; 

break; 
case MYGAD_STRING2 : 

/* String gadgets report GADGETUP' s */ 

printf ( "String gadget 2: '%s'.\n", 

((struct Stringlnfo *) gad->SpecialInf o) ->Buf f er) ; 

break; 



} 



case MYGAD_STRING3 : 

/* String gadgets report GADGETUP's */ 
printf ( "String gadget 3: '%s'.\n", 

((struct Stringlnfo *) gad->SpecialInf o) ->Buf f er) ; 
break; 
case MYGAD_BUTTON : 

/* Buttons report GADGETUP's (button resets slider to 10) */ 
printf ( "Button was pressed, slider reset to 10. \n"); 
*slider_level = 10; 

GT_SetGadgetAttrs (my_gads [MYGAD_SLIDER] , win, NULL, 
GTSL_Level, *slider_level , 
TAG_END) ; 
break; 
} 



/* 

** Function to handle vanilla keys. 

*/ 

VOID handleVanillaKey (struct Window *win, UWORD code, 
WORD *slider_level , struct Gadget *my_gads[]) 

{ 

switch (code) 

{ 

case ' v' : 

/* increase slider level, but not past maximum */ 
if (++*slider_level > SLIDER_MAX) 

*slider_level = SLIDERJVLAX; 
GT_SetGadgetAttrs (my_gads [MYGAD_SLIDER] , win, NULL, 
GTSL_Level, *slider_level , 
TAG_END) ; 
break; 
case 'V : 

/* decrease slider level, but not past minimum */ 
if (--*slider_level < SLIDER_MIN) 

*slider_level = SLIDER_MIN; 
GT_SetGadgetAttrs (my_gads [MYGAD_SLIDER] , win, NULL, 
GTSL_Level, *slider_level , 
TAG_END) ; 
break; 
case ' c' : 
case ' C' : 

/* button resets slider to 10 */ 
*slider_level = 10; 

GT_SetGadgetAttrs (my_gads [MYGAD_SLIDER] , win, NULL, 
GTSL_Level, *slider_level , 
TAG_END) ; 
break; 
case ' f ' : 
case ' F' : 

ActivateGadget (my_gads [MYGAD_STRING1] , win, NULL) ; 
break; 
case ' s' : 
case ' S' : 

ActivateGadget (my_gads [MYGAD_STRING2] , win, NULL) ; 
break; 
case ' t ' : 
case "I" : 

ActivateGadget (my_gads [MYGAD_STRING3 ] , win, NULL) ; 
break; 
} 
} 

/* 

** Here is where all the initialization and creation of GadTools gadgets 
** take place. This function requires a pointer to a NULL-initialized 
** gadget list pointer. It returns a pointer to the last created gadget, 
** which can be checked for success/failure. 

*/ 

struct Gadget *createAHGadgets (struct Gadget **glistptr, void *vi, 

UWORD topborder, WORD slider_level , struct Gadget *my_gads[]) 
{ 



struct NewGadget ng; 
struct Gadget *gad; 

/* All the gadget creation calls accept a pointer to the previous gadget, and 
** link the new gadget to that gadget's NextGadget field. Also, they exit 
** gracefully, returning NULL, if any previous gadget was NULL. This limits 
** the amount of checking for failure that is needed. You only need to check 
** before you tweak any gadget structure or use any of its fields, and finally 
** once at the end, before you add the gadgets. 
*/ 

/* The following operation is required of any program that uses GadTools. 
** It gives the toolkit a place to stuff context data. 

*/ 

gad = CreateContext (glistptr) ; 



/* Since the NewGadget structure is unmodified by any of the CreateGadget ( ) 

** calls, we need only change those fields which are different. 

*/ 



ng.ng_Lef tEdge 

ng . ng_TopEdge 

ng.ng_Width 

ng.ng_Height 

ng . ng_GadgetText 

ng . ng_Text At t r 

ng.ng^Visuallnf o 

ng.ng_GadgetID 

ng.ng_Flags 



14 0; 

2 0+topborder ; 

2 00; 

12; 

"_Volume : " , 

&Topaz80; 

vi ; 

MYGAD_SLIDER; 

NG HIGHLABEL; 



my_gads [MYGAD_SLIDER] = gad 

GTSL_Min, 
GTSL_Max, 
GTSL_Level, 
GTSL_LevelFormat , 
GTSL_MaxLevelLen, 
GT_Underscore , 
TAG END) ; 



CreateGadget (SLIDER_KIND, gad, &ng, 
SLIDER_MIN, 
SLIDER_MAX, 
slider_level , 
"%21d", 
2, 



ng . ng_TopEdge 4 

ng.ng_Height 

ng . ng_GadgetText 

ng.ng_GadgetID 



20; 
14; 

"_First : " ; 
MYGAD STRING1; 



my_gads [MYGAD_STRING1] = gad = CreateGadget (STRING_KIND, gad, &ng, 
GTST_String, "Try pressing", 
GTST_MaxChar s , 5 0, 
GT_Underscore, '_' , 
TAG END) ; 



ng . ng_TopEdge += 20; 

ng.ng_GadgetText = "_Second:"; 

ng.ng_GadgetID = MYGAD_STRING2 ; 

my_gads [MYGAD_STRING2 ] = gad = CreateGadget ( STRING_KIND , 

GTST_String, "TAB or Shift-TAB", 

GTST_MaxChar s , 5 0, 

GT_Underscore, '_' , 

TAG END) ; 



gad , &ng , 



ng . ng_TopEdge += 20; 

ng.ng_GadgetText = "_Third:"; 

ng.ng_GadgetID = MYGAD_STRING3 ; 

my_gads [MYGAD_STRING3 ] = gad = CreateGadget (STRING_KIND, gad, &ng, 

GTST_String, "To see what happens!", 

GTST_MaxChar s , 5 0, 

GT_Underscore, '_' , 

TAG END) ; 



ng.ng_Lef tEdge 4 

ng . ng_TopEdge 4 

ng.ng_Width 

ng.ng_Height 

ng . ng_GadgetText 

ng.ng_GadgetID 



50; 

20; 

100; 

12; 

"_Click Here" , 

MYGAD BUTTON; 



ng.ng_Flags = 0; 

gad ■ CreateGadget (BUTTON_KIND, gad, &ng, 

GT_Underscore, '_' , 

TAG_END) ; 
return (gad) ; 
} 

/* 

** Standard message handling loop with GadTools message handling functions 
** used (GT_GetIMsg() and GT_ReplyIMsg ( ) ) . 

*/ 

VOID process_window_events (struct Window *mywin, 
WORD *slider_level , struct Gadget *my_gads[]) 

{ 

struct IntuiMessage *imsg; 

ULONG imsgClass; 

UWORD imsgCode ; 

struct Gadget *gad; 

BOOL terminated = FALSE; 

while (! terminated) 

{ 

Wait (1 << mywin- >UserPort - >mp_SigBit ) ; 

/* GT_GetIMsg() returns an IntuiMessage with more friendly information for 
** complex gadget classes. Use it wherever you get IntuiMessages where 
** using GadTools gadgets. 

*/ 

while ((! terminated) && 

(imsg = GT_GetIMsg (mywin->UserPort) ) ) 

{ 

/* Presuming a gadget, of course, but no harm... 

** Only dereference this value (gad) where the Class specifies 

** that it is a gadget event. 

*/ 

gad = (struct Gadget *) imsg->IAddress ; 

imsgClass = imsg->Class; 
imsgCode = imsg->Code; 

/* Use the toolkit message-replying function here... */ 
GT_ReplyIMsg (imsg) ; 

switch (imsgClass) 

{ 

/* WARNING WARNING WARNING WARNING WARNING 

** GadTools puts the gadget address into IAddress of IDCMP_MOUSEMOVE 
** messages. This is NOT true for standard Intuition messages, 
** but is an added feature of GadTools. 

*/ 

case IDCMP_GADGETDOWN : 
case IDCMP_MOUSEMOVE : 
case IDCMPJ3ADGETUP : 

handleGadgetEvent (mywin, gad, imsgCode, slider_level , my_gads) ; 

break; 
case IDCMP_VANILLAKEY: 

handleVanillaKey (mywin, imsgCode, slider_level, my_gads) ; 

break; 
case IDCMP_CLOSEWINDOW: 

terminated = TRUE; 

break; 
case IDCMP_REFRESHWINDOW: 

/* With GadTools, the application must use GT_BeginRef resh ( ) 

** where it would normally have used BeginRef resh ( ) 

*/ 

GT_BeginRef resh (mywin) ; 
GT_EndRef resh (mywin, TRUE) ; 
break; 
} 
} 
} 



/* 

** Prepare for using GadTools, set up gadgets and open window. 
** Clean up and when done or on error. 

*/ 

VOID gadtoolsWindow(VOID) 

{ 

struct TextFont *font; 

struct Screen *mysc; 

struct Window *mywin; 

struct Gadget *glist, *my_gads [4] ; 

void *vi; 

WORD slider_level = 5; 

UWORD topborder; 

/* Open topaz 8 font, so we can be sure it's openable 
** when we later set ng_TextAttr to &Topaz80: 

*/ 

if (NULL == (font = OpenFont (&Topaz80) ) ) 

errorMessage ( "Failed to open Topaz 80"); 
else 

{ 

if (NULL == (mysc = LockPubScreen (NULL) ) ) 

errorMessage ( "Couldn't lock default public screen"); 
else 

{ 

if (NULL == (vi = GetVisualInfo(mysc, TAG_END) ) ) 

errorMessage( "GetVisuallnf o ( ) failed"); 
else 

{ 

/* Here is how we can figure out ahead of time how tall the */ 
/* window's title bar will be: */ 

topborder = mysc->WBorTop + (mysc->Font->ta_YSize + 1) ; 

if (NULL == createAHGadgets (&glist , vi , topborder, 

slider_level , my_gads) ) 
errorMessage ( "createAHGadgets ( ) failed"); 
else 

{ 

if (NULL == (mywin = OpenWindowTags (NULL, 

WA_Title, "GadTools Gadget Demo", 
WA_Gadgets, glist, WA_AutoAdjust , TRUE, 
WA_Width, 400, WA_MinWidth, 50, 
WA_InnerHeight, 140, WAJMinHeight , 50, 
WA_DragBar, TRUE, WAJDepthGadget , TRUE, 
WA_Activate, TRUE, WA_CloseGadget , TRUE, 
WA_SizeGadget, TRUE, WA_SimpleRef resh, TRUE, 
WA_IDCMP, IDCMP_CLOSEWINDOW | IDCMP_REFRESHWINDOW | 
IDCMPJVANILLAKEY | SLIDERIDCMP | STRINGIDCMP | 
BUTTONIDCMP, 
WA_PubScreen, mysc, 
TAG_END) ) ) 
errorMessage( "OpenWindow ( ) failed"); 

else 

{ 

/* After window is open, gadgets must be refreshed with a 

** call to the GadTools refresh window function. 

*/ 

GT_Ref reshwindow (mywin, NULL) ; 

process_window_events (mywin, &slider_level, my_gads) ; 

CloseWindow (mywin) ; 
} 
} 
/* FreeGadgets ( ) even if createAHGadgets ( ) fails, as some 
** of the gadgets may have been created... If glist is NULL 
** then FreeGadgets ( ) will do nothing. 

*/ 

FreeGadgets (glist) ; 
FreeVisuallnf o (vi) ; 

} 
UnlockPubScreen (NULL, mysc); 



CloseFont (font) ; 
} 
} 

/* 

** Open all libraries and run. Clean up when finished or on error.. 

*/ 

void main (void) 

{ 

if (NULL == (IntuitionBase = OpenLibrary ( "intuition. library" , 37))) 

errorMessage ( "Requires V37 intuition. library" ) ; 
else 

{ 

if (NULL == (GfxBase = OpenLibrary ( "graphics . library" , 37))) 

errorMessage ( "Requires V37 graphics . library" ) ; 
else 

{ 

if (NULL == (GadToolsBase = OpenLibrary ( "gadtools . library" , 37))) 

errorMessage ( "Requires V37 gadtools . library" ) ; 
else 

{ 

gadtoolsWindow ( ) ; 

CloseLibrary (GadToolsBase) ; 

} 
CloseLibrary (GfxBase) ; 

} 
CloseLibrary (IntuitionBase) ; 

} 
} 

Restrictions on GadTools Gadgets 

There is a strict set of functions and operations that are permitted on GadTools gadgets. Even if a technique is 
discovered that works for a particular case, be warned that it cannot be guaranteed and should not be used. If the 
trick concocted only works most of the time, it may introduce subtle problems in the future. 

Never selectively or forcibly refresh gadgets. The only gadget refresh that should ever be performed is the initial 
GT_RefreshWindow() after a window is opened with GadTools gadgets attached. It is also possible to add 
gadgets after the window is opened by calling AddGlistQ and RefreshGlist() followed by GT_RefreshWindow(). 
These refresh functions should not be called at any other time. 

GadTools gadgets may not overlap with each other, with other gadgets or with other imagery. Doing this to 
modify the gadget's appearance is not supported. 

GadTools gadgets may not be selectively added or removed from a window. This has to do with the number of 
Intuition gadgets that each call to CreateGadget() produces and with refresh constraints. 

Never use OnGadget() or OffGadgetQ or directly modify the GFLG_DISABLED Flags bit. The only approved 
way to disable or enable a gadget is to use GT_SetGadgetAttrs() and the GA_Disabled tag. Those kinds of 
GadTools gadgets that do not support GA_Disabled may not be disabled (for now). 

The application should never write into any of the fields of the Gadget structure or any of the structures that hang 
off it, with the exception noted earlier for GENERIC_KIND gadgets. Avoid making assumptions about the 
contents of these fields unless they are explicitly programmer fields (GadgetID and UserData, for example) or if 
they are guaranteed meaningful (LeftEdge, TopEdge, Width, Height, Flags). On occasion, the program is 
specifically invited to read a field, for example the Stringlnfo->Buffer field. 

GadTools gadgets may not be made relative sized or relative positioned. This means that the gadget flags 
GFLG_RELWIDTH, GFLG_RELHEIGHT, GFLG_RELBOTTOM and GFLG_RELRIGHT may not be specified. 
The activation type of the gadget may not be modified (for example changing GACT_IMMEDIATE to 
GACT_REL VERIFY). The imagery or the highlighting method may not be changed. 
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These restrictions are not imposed without reason; subtle or blatant problems may arise now or in future versions 
of GadTools for programs that violate these guidelines. 



Documented Side-Effects 

There are certain aspects of the behavior of GadTools gadgets that should not be depended on. This will 
current applications remain compatible with future releases of the GadTools library. 



help 



When using GT_FilterlMsg() and GT_PostFilterlMsg(), never make assumptions about the message before or 
after filtering. I.e., do not interpret the unfiltered message, assume that it will or will not result in certain kinds of 
filtered message or assume it will result in a consumed message (i.e., when GT_FilterlMsg() returns NULL). 

IDCMP_INTUITICKS messages are consumed when a scroller's arrows are repeating. That is, 
IDCMPJNTUITICKS will not be received while the user is pressing a scroller arrows. Do not depend or rely on 
this side effect, though, it will not necessarily remain so in the future. 

A single call to CreateGadgetQ may create one or more actual gadgets. These gadgets, along with the 
corresponding code in GadTools, define the behavior of the particular kind of GadTools gadget requested. Only 
the behavior of these gadgets is documented, the number or type of actual gadgets is subject to change. Always 
refer to the gadget pointer received from CreateGadget() when calling GT_SetGadgetAttrs(). Never refer to 
other gadgets created by GadTools, nor create code which depends on their number or form. 

For text-display gadgets, the GTTX_CopyText tag does not cause the text to be copied when the text is later 
changed with GTTX_Text. 

The PLACETEXT ng_Flags are currently ignored by GENERIC_KIND gadgets. However, this may not always be 
so. 

All GadTools gadgets set GADTOOL_TYPE in the gadget's GadgetType field. Do not use this flag to identify 
GadTools gadgets, as this flag is not guaranteed to be set in the future. 

The palette gadget subdivides its total area into the individual color squares. Do not assume that the subdivision 
algorithm won't change. 



Function Reference 



The following are brief descriptions of the Intuition functions discussed in this chapter. See the "Amiga ROM 
Kernel Reference Manual: Includes and Autodocs" for details on each function call. All of these functions require 
Release 2 or a later version of the operating system. 

Table 15-2: GadTools Library Functions 
Desc ri p ti o n 



Func ti on 



CrealeGadyelAO 

CreateGadget() 

FreeGadgets() 

GT_SetGadgetAttrsA() 

GT_SetGadgetAttrs() 

CreateContextQ 



Cr e ateM en usA() 

CreateMenus() 

FreeMenus() 

LayoutMenultemsAQ 

LayoutMenultems() 

LayoutMenusA() 

LayoutMenusQ 



GT_Gel l Msg() 

GT_ReplylMsg() 
GT_FilterlMsg() 
GT_PostFilterlMsg() 



GT_RefreshWindow() 

GT_BeginRefresh() 

GT_EndRefresh() 



DrawBevelBoxA() 

DrawBevelBox() 

GetVisuallnfoA() 

GetVisuallnfo() 

FreeVisuallnfoQ 



Allocate GadTools gadget, lag array form. — 

Allocate GadTools gadget, varargs form. 

Free all GadTools gadgets. 

Update gadget, tag array form. 

Update gadget, varargs form. 

Create a base for adding GadTools gadgets. 



A ll ocate GadToo l s menu structures, tag array form. 
Allocate GadTools menu structures, varargs form. 
Free menus allocated with CreateMenus(). 
Format GadTools menu items, tag array form. 
Format GadTools menu items, varargs form. 
Format GadTools menus, tag array form. 
Format GadTools menus, varargs form. 



GadTools gadyel compalible version of GelMsg(). 

GadTools gadget compatible version of ReplyMsg(). 
Process GadTools gadgets with GetMsg()/ReplyMsg(). 
Process GadTools gadgets with GetMsgQ/ReplyMsgQ. 



Display GadTools gadget imagery after creation. 
GadTools gadget compatible version of BeginRefresh(). 
GadTools gadget compatible version of EndRefreshQ. 



Draw a 3D box, lag array form. 

Draw a 3D box, varargs form. 

Get drawing information for GadTools, tag array form. 
Get drawing information for GadTools, varargs form. 
Free drawing information for GadTools. 



Chapter 16 
ASL LIBRARY 



This chapter describes the asl. library. The sole purpose of this library is to provide standard file and font 
requesters for application programs. 

It is easier to understand the asl. library if you are familiar with some basic concepts of the Amiga operating 
system, especially Tagltem arrays (described in the "Utility Library" chapter), Intuition screens and windows, 
graphics library font structures, and AmigaDOS pattern matching. 



About Requesters 



Requesters are temporary sub-windows used for confirming actions or selecting options. The most common type 
of requester is a file requester which is used to pick a file name for a load or save operation. 

Under 1 .3 (V34) and earlier versions of the Amiga operating system there was limited support for requesters. 
Intuition provides simple requesters which can be used to request responses such as OK or Cancel from the user. 
More elaborate Intuition requesters can be created by adding additional features such as string gadgets, however 
the result of this is that each application writer develops their own style of requester. Hence, the asl. library has 
been added to Release 2 of the Amiga operating system to make requesters more consistent. With asl. library, 
requesters are also much easier to create and take less memory. 

The ASL Library Requires Release 2. The asl. library requires Release 2 of the Amiga 
operating system, so only applications running under Release 2 and later versions of the 
Amiga OS can call its functions. 

Requesters are very flexible and can be used for many different purposes. The Release 2 asl. library supports the 
two most common type of requesters: 

File requesters for choosing a file name in a load or save operation 

Font requesters for choosing a font in a text operation 
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Creating a File Requester 

Opening an ASL requester requires the use of three functions: 

APTR request = AllocAslRequest ( unsigned long type, struct Tagltem *tagList ); 
BOOL success = AslRequest ( APTR request, struct Tagltem *tagList ) ; 
void FreeAslRequest ( APTR request ) ; 

The first function you should call is AllocAslRequest(). This allocates the main data structure you will use, either 
a FileRequester structure or a FontRequester structure. You specify the type of requester you want for 
AllocAslRequest() by setting the type argument. This can be one of two values defined in <libraries/asl.h>: 
either ASLFileRequest, to ask for a FileRequester structure, or ASLFontRequest, to ask for a FontRequester 
structure. 

Here's a listing of the FileRequester structure. (The FontRequester structure is discussed in more detail later in 
this chapter.) 

struct FileRequester 

{ 

/* (from <libraries/asl .h>) */ 
APTR rf_Reservedl; 
BYTE *rf_File; /* Filename pointer */ 



BYTE 

CPTR 

UBYTE 

UBYTE 

APTR 

WORD 

WORD 

WORD 

LONG 



*rf_Dir; /* Directory name pointer 

r f _Re s e rve d2 

rf_Reserved3 

rf_Reserved4 

rf_Reserved5 

rf_Lef tEdge, rf_TopEdge; /* Preferred window pos 



rf_Width,rf_Height; 
rf _Reserved6 ; 
rf _NumArgs ; 



struct WBArg *rf_ArgList; 
APTR rf_UserData; 
APTR rf_Reserved7; 
APTR rf_Reserved8; 
BYTE *rf Pat; 



/* Preferred window size */ 
/* A-la WB Args, for multiselects */ 
/* Applihandle (you may write!!) */ 



/* Pattern match pointer */ 

/* note - more reserved fields follow */ 



Whichever requester type you use, you must allocate the requester structure with the AllocAslRequest() function 
call. Do not create the data structure yourself. The values in this structure are for read access only. Any 
changes to them must be performed only through asl. library function calls. 

Once you have set up a requester structure with AllocAslRequestQ, call AslRequestQ to make the requester 
appear on screen. AslRequest() takes the requester data structure as an argument using it as a specification for 
the requester that it creates on screen. 



Select Icon to Open 



Connodities.infci 
Graph icDunp. info 
HDBackup. info 
HDToolbox.info 
HE 



InitPrinter.info 
KeyShow. info 

MEnacs.info 
PrintFiles.info 
Connodities 



IBIBI 



Drawer svs: TqdIs 




File IconEdit.info 


Open | Disks Parent 


Cancel 




Figure 16-1: The ASL File Requester 
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AslRequest() is always synchronous to the calling program. That is, control does not return to your program until 
the user makes a selection or cancels. AslRequestQ returns TRUE, if the user selects a file (or a font). In that 
case the file (or font) name that the user selected is returned in the requester data structure. AslRequestQ 
returns FALSE if the user cancels the requester or the requester failed for some reason. 

When you have finished with a requester use the FreeAslRequest() function to deallocate the requester data 
structure. 

Specifying Requester Options with Tagltems 

Both AllocAslRequestQ and AslRequestQ accept a Tagltem array or tag list as an argument. The tag list is 
used to initialize or alter the values in the requester data structure. 



A single Tagltem consists of a tag name and an associated tag value. Tag items that apply to the asl. library are 



defined in <libraries/asl.h>. The basic tag items (used in the first example listed below) are: 

Requester Tag Name Used For 

ASLJHail String to place in the title bar of the requester window 

ASL_Width Requester window width 

ASLJHeight Requester window height 

ASL_LeftEdge Requester window y origin 

ASL_TopEdge Requester window x origin 

ASLOKText String to place in OK gadget of requester 

ASLCancelText String to place in Cancel gadget of requester 

ASL_File Default file name (for file requesters only) 

ASL_Dir Default directory name (for file requesters only) 

Note that you are currently limited to about six characters for the replacement text if you use either the 
ASL_OKText or ASL_CancelText tags to change the text that appears in the OK and Cancel gadgets. 

The contents of an ASL requester data structure are preserved across calls to AslRequest(). So, until the 
requester is freed, tag settings and user selections will remain in the data structure unless they are altered by tags 
in subsequent calls to AslRequest(). This is very useful because it allows the requester to remember and 
redisplay the user's previous selections. However, this also means that the programmer must assure that any 
addresses passed in ASL tags remain valid, or are refreshed on each call to AslRequest(). 

Generally, options that you wish to specify only once, such as the initial position and size, should be specified as 
tags when you allocate the requester. Options that you wish to control for each use of the requester should be 
passed as tags each time the requester is opened with AslRequest(). 

Simple ASL File Requester Example 

Here is a short example showing how to create a file requester wil asl. library. If AslRequestQ returns TRUE then 
the rf_File and rf_Dir fields of the requester data structure contain the name and directory of the file the user 
selected. Note that the user can type in the name for the file and directory, whihc makes it possible for a file 
requester to retain a file and directory that do not (currently) exist. 
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;/* filereq.c - Execute me to compile me with SASC 5.10 

LC -bl -cfistq -v -y -J73 filereq.c 

Blink FROM LIB : c . o, f ilereq. o TO filereq LIBRARY LIB : LC . lib, LIB : Amiga . lib 

quit 



Here's a short example showing how to create a file requester with 
asl. library. If AslRequestO returns TRUE then the rf_File and 
rf_Dir fields of the requester data structure contain the name and 
directory of the file the user selected. Note that the user can type 



** in the a name for the file and directory, which makes it possible for 
** a file requester to return a file and directory that do not 
** (currently) exist. 

*/ 

#include <exec/types . h> 
#include <exec/libraries . h> 
#include <libraries/asl . h> 
#include <clib/exec_protos . h> 
#include <clib/asl_protos . h> 
#include <stdio.h> 

#ifdef LATTICE 

int CXBRK(void) { return(O); } /* Disable Lattice CTRL/C handling */ 

void chkabort (void) { return; } /* really */ 

#endif 

UBYTE *vers = "$VER: filereq 3 7.0"; 

#define MYLEFTEDGE 
#define MYTOPEDGE 
#define MYWIDTH 32 
#define MYHEIGHT 400 

struct Library *AslBase = NULL; 



struct Tagltem f rtags [] = 

{ 

ASL_Hail, (ULONG) "The RKM file requester", 

ASL_Height, MYHEIGHT, 

ASL_Width, MYWIDTH, 

ASL_LeftEdge, MYLEFTEDGE, 

ASL_TopEdge , MYTOPEDGE , 

ASLjDKText, (ULONG) "O KAY", 

ASL_CancelText, (ULONG) "not OK", 

ASL_File, (ULONG) "asl . library" , 

ASL_Dir, (ULONG) "libs :" , 

TAGJDONE 

}; 

void main(int argc, char **argv) 

{ 

struct FileRequester *fr; 

if (AslBase = OpenLibrary ( "asl . library" , 37L) ) 

{ 

if (fr = (struct FileRequester *) 

AllocAslRequest (ASL_FileRequest , f rtags) ) 

{ 

if (AslRequest (fr, NULL)) 

{ 

printf ( "PATH=%s FILE=%s\n" , fr->rf_Dir, fr->rf_File) ; 
printf("To combine the path and filename, copy the path\n"); 
printf ("to a buffer, add the filename with Dos AddPart ( ) .\n") ; 

} 

FreeAslRequest (fr) ; 

} 

else printf ("User Cancelled\n" ) ; 

CloseLibrary (AslBase) ; 
} 
} 

File Pattern Matching and Multiple Selects 

A file requester can filter out certain file and directory entries using the "wildcard" feature of AmigaDOS. To 
activate the wildcard feature for a file requester, you use the ASL_FuncFlags tag. Each bit in the ASL_FuncFlags 
tag item controls a special option of the requester depending on its type (file or font). See <\ibraries/asl.h> for a 
complete listing of the options that the ASL_FuncFlags tag controls. 
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File Requester Flag Used For 

FILF_PATGAD Enables the file name pattern matching gadget 

FILF_MULTISELECT Enables multiple selection of files 

FILF_NEWIDCMP Use separate IDCMP for requester sharing a custom screen (see below) 

FILF_SAVE Makes the file requester a save requester (see below) 

If the FILF_PATGAD bit of the ASL_FuncFlags tag is set, the file requester will appear with a "Pattern" gadget in 
addition to the usual file name and directory name gadgets. The user can type an AmigaDOS wildcard pattern 
into this gadget and the pattern will be used to limit the file names that appear in the requester. An application 
can also supply a default pattern using the ASL_Pattern tag item. A hidden unchangeable pattern can be created 
by supplying an ASL_Pattern without a FILF_PATGAD gadget. Such invisible patterns should not be used if there 
is any reason that the user may need to access a file which does not match the pattern. 

Another feature of the ASL file requester is multiple selection. When multiple selection is enabled, the user can 
choose more than one file name in a single directory by selecting names in the requester's scrolling list gadget 
with the mouse. This option, like pattern matching, is set up with the ASL_FuncFlags tag. 

If the FILF_MULTISELECT bit of the ASL_FuncFlags tag is set, the file requester will allow multiple selection. 
When the user selects several file names through the multiple selection feature, the FileRequester's rf_NumArgs 
field contains the number of files selected and the rf_ArgList field contains a pointer to an array of WBArg 
structures (defined in <workbench/startup.h>). There is a WBArg structure containing a file name for each file the 



user selected. 

The following example illustrates a file requester with both a pattern matching gadget and multiple selection 
enabled. 

;/* filepat.c - Execute me to compile me with SASC 5.10 

LC -bl -cfistq -v -y -J73 filepat.c 

Blink FROM LIB : c . o, f ilepat . o TO filepat LIBRARY LIB : LC . lib, LIB : Amiga . lib 

quit 

*/ 

#include <exec/types .h> 
#include <intuition/intuition.h> 
#include <intuition/screens .h> 
# include <graphi cs/di splay inf o.h> 
#include <libraries/asl . h> 
#include <workbench/startup.h> 

#include <clib/asl_protos . h> 
#include <clib/exec_protos . h> 
#include <clib/intuition_protos . h> 
#include <stdio.h> 

#ifdef LATTICE 

int CXBRK(void) { return(O); } /* Disable Lattice CTRL/C handling */ 

void chkabort (void) { return; } /* really */ 

#endif 

UBYTE *vers = "$VER: filepat 37. Ob- 
struct Library *AslBase = NULL; 
struct Library *IntuitionBase = NULL; 
struct Screen *screen = NULL; 
struct Window *window = NULL; 

void main (int argc, char **argv) 

{ 

struct FileRequester *fr; 
struct WBArg *frargs; 
int x ; 

if (AslBase = OpenLibrary ( "asl . library" , 37L) ) 

{ 

if (IntuitionBase = (struct IntuitionBase *) 

OpenLibrary ( " intuition . library" , 37L) ) 

{ 

if (screen = (struct Screen *) OpenScreenTags (NULL, 
SA_DisplayID, HIRESLACE_KEY, 
SA_Title, "ASL Test Screen", 
TAG_END) ) 

{ 

if (window = (struct Window *) OpenWindowTags (NULL, 
WA_CustomScreen, screen, 

WA_Title, "Demo Customscreen, File Pattern, Multi-select", 
WA_Flags, WINDOWDEPTH | WINDOWDRAG, 
TAG END) ) 



{ 



if (fr = (struct FileRequester *) 

AllocAslRequestTags (ASL_FileRequest , 

ASL_Hail, (ULONG) "FilePat/MultiSelect Demo", 
ASL_Dir, (ULONG) "libs :" , 
ASL_File, (ULONG) "asl . library" , 

/* Initial pattern string for pattern matching */ 
ASL_Pattern, (ULONG) " ~ (rexx#? | math#? ) ", 

/* Enable multiselection and pattern match gadget */ 
ASL_FuncFlags , FILF_MULTISELECT | FILF_PATGAD, 

/* This requester comes up on the screen of this 
** window (and uses window's message port, if any) . 

*/ 

ASL Window, window, 



TAG_DONE) ) 

{ 

/* Put up file requester */ 
if (AslRequest (f r, OL) ) 

{ 

/* If the file requester's rf_NumArgs field 
** is not zero, the user multiselected. The 
** number of files is stored in rf _NumArgs . 

*/ 

if (f r->rf_NumArgs) 

{ 

/* rf_ArgList is an array of WBArg structures 

** (see <workbench/startup.h>) . Each entry in 

** this array corresponds to one of the files 

** the user selected (in alphabetical order) . 

*/ 

frargs = f r->rf_ArgList ; 

/* The user multiselected, step through 
** the list of selected files. 

*/ 

for ( x=0; x < f r->rf_NumArgs ; x++ ) 

printf ( "Argument %d: PATH=%s FILE=%s\n", 
x, fr->rf_Dir, frargs [x] .wa_Name) ; 

} 

else 

/* The user didn't multiselect, use the 

** normal way to get the file name. 

*/ 

printf ( "PATH=%s FILE=%s\n", fr->rf_Dir, fr->rf_File) ; 

} 

/* Done with the FileRequester, better return it */ 
FreeAslRequest (fr) ; 

} 

CloseWindow (window) ; 

} 

CloseScreen (screen) ; 

} 

CloseLibrary (IntuitionBase) ; 

} 

CloseLibrary (AslBase) ; 

} 
} 
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The previous example demonstrates two alternate functions for creating and using ASL requesters: 

APTR AllocAslRequestTags ( unsigned long type, Tag Tagl , ... ) ; 
BOOL AslRequestTags ( APTR request, Tag Tagl, ... ); 

AllocAslRequestTagsQ can be used instead of AllocAslRequestQ to allocate and set up the file requester. 
This is an amiga.lib function that will accept Tagltems directly in its parameter list, rather than a pointer to an 
array of Tag Items. 

Similarly, AslRequestTagsQ will accept Tagltems directly instead of requiring a pointer to an array of Tagltems 
as AslRequest() does. 

ASL Requesters and Custom Screens 

An application that uses a custom screen normally wants its requesters to open on its screen. Using the 
ASL_Window tag, a program can associate a requester with a specific window so that the requester appears on 
the same screen as the window. The ASL_Window tag is followed by a pointer to a window structure. 
ASL_Window works with both file and font requesters. The example above shows how the ASL_Window tag is 
used with a file requester. 

Normally, a requester associated with a window (using ASL_Window) shares that window's IDCMP port for its 
communication. An application may not want to share an IDCMP port with the requester. Using the 
ASL_FuncFlags tag, a program can ask for a requester that creates its own IDCMP port. There are two flags that 



accomplish this. The first, FILF_NEWIDCMP, is used on file requesters. The other, FONF_NEWIDCMP, is used 
on font requesters. 

The Save Requester 

The save requester is a special type of file requester used for save operations. It differs from the regular ASL file 
requester in several ways. First, the color of the text making up the file names and the background color are 
interchanged. This makes it more apparent to the user that they are looking at a save requester (instead of the 
usual load requester). 

Another difference, is that a save requester does not allow the user to select an existing file name by 
double-clicking on an entry in the scrolling list gadget. This helps prevent the user from accidentally overwriting 
the wrong file. 

Save requesters can also create directories. If the user types a directory name into the save requester and the 
directory doesn't exist, the save requester will create that directory (after getting the user's permission via another 
requester). 

To create a save requester, set the FILF_SAVE flag of the ASL_FuncFlags tag. Remember that ASL tags and flag 
values are preserved across calls to AslRequestQ, so if you use a save requester, you must clear the 
FILF_SAVE bit and reset your ASL_FuncFlags when you want a load requester. Note that it does not make sense 
to have multiselection in a save requester, so the FILF_SAVE flag overrides the FILF_MULTISELECT flag. 
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The Directory Requester 

Sometimes a program may only require a directory name from the user. There is another variation on asl. library's 
file requester that allows this. The ASL_ExtFlags1 tag contains a flag bit to toggle this option. If the 
FIL1 F_NOFILES flag of ASL_ExtFlags1 is set, the requester will appear without a string gadget for file names and 
will display only directory names in the scrolling list gadget. When AslRequestQ (or AslRequestTags() ) returns 
successfully, the rf_Dir field of the FileRequester structure contains the name of the directory the user selected. 

Another flag defined for ASL_ExtFlags1 is FIL1 F_MATCHDIRS. If file pattern matching is on (see the 
FILF_PATGAD flag for ASL_FuncFlags, setting FIL1 F_MATCHDIRS tells the file requester to pattern match 
directory names as well as file names. Of course, if both of these ASL_ExtFlags1 flags are set, the requester will 
only pattern match directory names. 



Creating a Font Requester 



The ASL library also contains a font requester. Using the font requester is very similar to using the file requester. 
First, allocate a requester structure with AllocAslRequestQ or AllocAslRequestTagsQ. The type should be set 
to ASL_FontRequest in order to get a FontRequester structure: 

struct FontRequester 

{ 

APTR fo_Reservedl [2] ; 

struct TextAttr fo_Attr; /* Returned TextAttr */ 

UBYTE fo_FrontPen; /* Returned pens, if selected */ 

UBYTE fo_BackPen; 

UBYTE f o_DrawMode ; 

APTR fo_UserData; 

/* missing from asl.h but present in this structure */ 

SHORT fo_LeftEdge, fo_TopEdge, fo_Width, fo_Height; 

}; 

Once the requester is set up, call AslRequestQ or AslRequestTags() to make the requester appear on screen. 
These functions return TRUE if the user makes a selection. In that case, the font selected is returned as a 
TextAttr structure in the fo_Attr field of the FontRequester structure. (The TextAttr structure is defined in 
<graphics/text.h>. See the Amiga ROM Kernel Manual: Includes and Autodocs for a complete listing.) If the user 
cancels the font requester FALSE is returned. 
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Figure 16-2: The ASL Font Requester 

When the requester is no longer needed, call FreeAslRequest() to deallocate the requester data structure. 
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Specifying Font Requester Options with Tagltems 

As with a file requester, the font requester is specified with a Tagltem list. There are several tags that are specific 
to the font requester: 



Font Requester Tag Name 

ASLFontName 

ASL_FontHeight 

ASL_FontStyles 

ASL_FontFlags 

ASL_FrontPen 

ASL_BackPen 

ASL_ModeList 

ASL_MinHeight 

ASL_MaxHeight 



Used For 

Default font (fo_Attr.ta_Name) 

Default font size (fo_Attr.ta_YSize) 

Default font style (fo_Attr.ta_Style) 

Default font flags (fo_Attr.ta_Flags) 

Default font color (fo_FrontPen) 

Default font background color (fo_BackPen) 

Alternate strings for the drawing mode gadget (see below) 

Minimum font height the requester will display 

Maximum font height the requester will display 



Note that the last two tags only limit the range of font sizes that the font requester displays, the user is free to type 
in any value. 

Font requesters have additional special options that are controlled through the ASL_FuncFlags tag. This tag 
works the same way as it does with file requesters but with different options available. Recall that the data for this 
tag is divided into bit fields, each of which controls a requester option. The flags used with the ASL_FuncFlags 
tag in a font requester are defined in <libraries/asl.h>: 



Font Requester Flags 

FONF_FRONTCOLOR 
FONF_BACKCOLOR 
FONF_STYLES 
FONF_FIXEDWIDTH 
FONF DRAWMODE 



Used For 

Enables font color selection gadgets 
Enables font background color selection gadget 
Enables font style selection gadget 
Limits display to fixed width fonts only 
Enables font draw mode gadget 



A simple font requester (one without any of the above FONF_ flags set) only lets the user choose a font and a Y 
size. Setting the flags above adds options to the font requester. FONFFRONTCOLOR and 
FONF_BACKCOLOR add color selection gadgets to the requester, one for choosing a font's foreground color 
(labeled "Text") and the other for choosing the background color (labeled "Field"). The font requester records the 
user's setting in the FontRequester's fo_FrontPen and fo_BackPen fields. 



FONF_STYLES sets up several gadgets to choose the style of the font (bold, italics, underline). The font 
requester saves these settings in the fo_Attr.ta_Style bit field according to the style flags defined in 
<graphics/text.h>. FONF_FIXEDWIDTH limits the font name display to fixed width (non-proportional) fonts (note 
that this does not prevent the user from typing in a proportional font name). 

FONF_DRAWMODE adds a cycle gadget to the font requester so the user can choose the draw mode. The draw 
mode is saved in the requester's fo_DrawMode field. The number stored there corresponds to the draw mode's 
position in the gadget's cycle. 

The draw mode cycle gadget initially is labeled "Mode" and has three elements in its cycle: "JAM1", "JAM2", and 
"Complement". These yield a result of 0, 1 , and 2, respectively. It is possible to change the names and number 
of draw modes with the ASL_ModeList tag. This tag accepts a pointer to an array of strings. The first string 
replaces "Mode" as the label for the draw mode cycle gadget. The strings that follow replace the elements of the 
cycle gadget. The last entry in the array has to be NULL to tell the requester where the list of entries ends. 

ASL Library 423 

Example Font Requester 

The following example illustrates how to use a font requester. 

;/* fontreq.c - Execute me to compile me with Lattice 5.10 

LC -bl -cfistq -v -y - j 73 fontreq.c 

Blink FROM LIB : c . o, f ontreq. o TO fontreq LIBRARY LIB : LC . lib, LIB : Amiga . lib 

quit 

** The following example illustrates how to use a font requester. 
*/ 

#include <exec/types .h> 
#include <libraries/asl . h> 

#include <clib/asl_protos . h> 
#include <clib/exec_protos . h> 

#include <stdio.h> 

#ifdef LATTICE 

int CXBRK(void) { return(O); } /* Disable Lattice CTRL/C handling */ 

void chkabort (void) { return; } /* really */ 

#endif 

UBYTE *vers = "$VER: fontreq 3 7. Ob- 
struct Library *AslBase = NULL; 

/* Our replacement strings for the "mode" cycle gadget. The 
** first string is the cycle gadget's label. The other strings 
** are the actual strings that will appear on the cycle gadget. 
*/ 

UBYTE *modelist [] = 

{ 

"RKM Modes" , 
"Mode 0", 
"Mode 1", 
"Mode 2", 
"Mode 3", 
"Mode 4", 
NULL 

}; 

void main (int argc, char **argv) 

{ 

struct FontRequester *fr; 

if (AslBase = OpenLibrary ( "asl . library" , 37L) ) 

{ 

if (fr = (struct FontRequester *) 

AllocAslRequestTags (ASL_FontRequest , 



/* tell the requester to use my custom mode names */ 
ASL_ModeList, modelist, 

/* Supply initial values for requester */ 

ASL_FontName , (ULONG) "topaz . font " , 

ASL_FontHeight , 11L, 

ASL_FontStyles, FSF_BOLD | FSF_ITALIC, 

ASL_FrontPen, OxOOL, 

ASL_BackPen, 0x0 1L, 

/* Only display font sizes between 8 and 14, inclusive. */ 
ASL_MinHeight, 8L, 
ASL_MaxHeight, 14L, 

/* Give all the gadgetry, but only display fixed width fonts */ 
ASL_FuncFlags , FONF_FRONTCOLOR | FONF_BACKCOLOR | 

FONF_DRAWMODE | FONF_STYLES | FONF_FIXEDWIDTH, 
TAG_DONE) ) 

{ 

/* Pop up the requester */ 
if (AslRequest (fr, NULL)) 

{ 

/* The user selected something, report their choice */ 
printf ("%s\n YSize = %d Style = 0x%x Flags = 0x%x\n" 
" FPen = 0x%x BPen = 0x%x DrawMode = 0x%x\n", 
f r->f o_Attr . taName , 
fr->fo_Attr.ta_YSize, 
fr->fo_Attr.ta_Style, 
f r->fo_Attr . ta_Flags, 
f r->f o_FrontPen, 
f r->f o_BackPen, 
f r->f o_DrawMode) ; 

} 

else 

/* The user cancelled the requester, or some kind of error 
** occurred preventing the requester from opening. */ 
printf ( "Request Cancelled\n" ) ; 

FreeAslRequest (fr) ; 

} 

CloseLibrary (AslBase) ; 



Calling Custom Functions from a Requester 

The ASLJHookFunc tag passes an ASL requester a pointer to a custom function. The requester can use this 
function for two purposes. The first is to determine if the requester should display a particular file or font name. 
The other purpose is to process messages that the requester receives at its IDCMP port that are not meant for the 
requester. Hook functions are set up through flag values used with the ASL_FuncFlags tag: 

Hook Function Flag Used For 

FILFDOWILDFUNC Call user hook function on each name in a file requester 

FONF_DOWILDFUNC Call user hook function on each name in a font requester 

FILF_DOMSGFUNC Call user hook function for IDCMP messages not used by a file requester 

FONF_DOMSGFUNC Call user hook function for IDCMP messages not used by a font requester 

The FILF_DOWILDFUNC and FONF_DOWILDFUNC flags cause a requester to call the function you specify with 
the ASL_HookFunc tag for every file or font entry. The requester displays the file or font name only if your hook 
function tells it to. For a file requester, if your hook function returns a zero, the file requester will display the file 
name. For a font requester, if your hook function returns anything but zero, the font requester will display the font 
name and size. 

The FILF_DOMSGFUNC and FONF_DOMSGFUNC flags cause a requester to call your hook function whenever 
it receives an IntuiMessage that it cannot use at the IDCMP port that it shares with your window. (See the section 
on "ASL Requesters and Custom Screens" earlier in this chapter for more information about sharing IDCMP 
ports.) If the requester receives any messages that are not meant for the requester it will call your hook function 
(specified with the ASL_HookFunc tag). Your hook function is responsible for returning a pointer to the 
IntuiMessage. The requester will take care of replying to the message. 
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Parameters Passed to Custom Hook Functions 

A requester always passes three parameters to your custom hook function: 

ULONG MyHookFunc (ULONG type, CPTR object, CPTR AslRequester) 

If MyHookFunc() is called from a file requester doing _DOWILDFUNC, the three parameters are: 

type = FILF_DOWILDFUNC 

obj ect = pointer to an AnchorPath structure (from <dos/dosasl.h>) 
AslRequester = pointer to the FileRequester that called the hook function 
(Return a zero to display this file) 

The AnchorPath structure is a dos. library structure used in pattern matching. Refer to the AmigaDOS Manual, 
3rd Edition by Bantam Books for more information. 

If MyHookFunc() is called from a font requester doing _DOWILDFUNC, the three parameters are: 

type = FONF_DOWILDFUNC 

obj ect = pointer to a TextAttr structure (from <graphics/text.h>) 
AslRequester = pointer to the FontRequester that called the hook function 
(Return non-zero to display this particular font size) 

If MyHookFunc() is called from a file or font requester doing _DOMSGFUNC, the three parameters are: 

type = FILF_DOMSGFUNC (file requester) or FONF_DOMSGFUNC (font requester) 
obj ect = pointer to the IntuiMessage for the function to process 

AslRequester = pointer to the FileRequester or FontRequester that called the hook function 
(Return a pointer to the IntuiMessage) 

Notice that it is possible for a requester to use both _DOWILDFUNC and _DOMSGFUNC at the same time. Your 
hook function has to differentiate between the two cases by testing the type passed to it. It is not possible for a 
font and file requester to share a hook function for a _DOWILDFUNC, because FILF_DOWILDFUNC is defined to 
be the same value as FONF_DOWILDFUNC, so the hook function cannot tell if the object (from the prototype 
above) is a pointer to an AnchorPath structure or a pointer to a TextAttr structure. It is possible for font and file 
requesters to share one hook function for _DOMSGFUNC (even though FILF_DOMSGFUNC and 
FONF_DOMSGFUNC are equal) because, in this case, font and file requesters both call your hook function in the 
same manner. 

Example ASL Requester with Custom Hook Function 

The following example illstrates the use of a hook function for both _DOWILDFUNC and _DOMSGFUNC. 

;/* filehook.c - Execute me to compile me with Lattice 5.10 

LC -bl -cfistq -v -y -J73 filehook.c 

Blink FROM LIB : c . o, f ilehook . o TO filehook LIBRARY LIB : LC . lib, LIB : Amiga . lib 

quit 

** The following example illustrates the use of a hook function for 
** both _DOWILDFUNC and _DOMSGFUNC . 

*/ 

#include <exec/types .h> 
#include <intuition/intuition.h> 
#include <dos/dosasl . h> 
#include <libraries/asl . h> 

#include <clib/exec_protos . h> 
#include <clib/dos_protos . h> 
#include <clib/asl_protos . h> 
#include <clib/intuition_protos . h> 
#include <stdio.h> 



#ifdef LATTICE 

int CXBRK(void) { return(O); } /* Disable Lattice CTRL/C handling */ 

void chkabort (void) { return; } /* really */ 

#endif 

#define DESTPATLENGTH 2 

UBYTE *vers = "$VER: filehook 37.0"; 

CPTR HookFunc ( ) ; 

struct Library *AslBase = NULL; 
struct Library *IntuitionBase = NULL; 
struct Window *window = NULL; 

/* this is the pattern matching string that the hook function uses */ 
UBYTE *sourcepattern = " (#? . info) " ; 
UBYTE pat [DESTPATLENGTH] ; 

void main (int argc, char **argv) 

{ 

struct FileRequester *fr; 

if (AslBase = OpenLibrary ( "asl . library" , 37L) ) 

{ 

if (IntuitionBase = (struct IntuitionBase *) 

OpenLibrary ( " intuition . library" , 37L) ) 

{ 

/* This is a V37 dos. library function that turns a pattern matching 

** string into something the DOS pattern matching functions can 

** understand. 

*/ 

ParsePattern(sourcepattern, pat, DESTPATLENGTH); 

/* open a window that gets ACTIVEWINDOW events */ 
if (window = (struct Window *) OpenWindowTags (NULL, 

WA_Title, "ASL Hook Function Example", 

WA_IDCMP, IDCMP_ACTIVEWINDOW, 

WA_Flags, WFLG_DEPTHGADGET, 

TAG_END) ) 

{ 

if (fr = AllocFileRequest () ) 

{ 

if (AslRequestTags (f r, 

ASL_Dir, (ULONG) "SYS :Utilities " , 

ASL_Window, window, 

ASL_TopEdge, 0L, 

ASL_Height, 200L, 

ASL_Hail, (ULONG) "Pick an icon, select save", 

ASL_HookFunc , (ULONG) HookFunc , 

ASL_FuncFlags, FILF_DOWILDFUNC | FILFJDOMSGFUNC | FILF_SAVE, 

ASL_OKText , (ULONG) " Save " , 

TAG_DONE) ) 

{ 

printf ( "PATH=%s FILE=%s\n" , fr->rf_Dir, f r->rf_File) ; 
printf("To combine the path and filename, copy the path\n"); 
printf ("to a buffer, add the filename with Dos AddPart ( ) .\n") 

} 

FreeFileRequest (fr) ; 

} 

CloseWindow (window) ; 

} 

CloseLibrary (IntuitionBase) ; 

} 

CloseLibrary (AslBase) ; 



} 



CPTR HookFunc (LONG type, CPTR obj , struct FileRequester *fr) 

{ 

static BOOL returnvalue; 
switch (type) 



case FILF_DOMSGFUNC: 

/* We got a message meant for the window */ 

printf("You activated the window\n"); 

return (obj ) ; 

break; 
case FILF_DOWILDFUNC: 

/* We got an AnchorPath structure, should 
** the requester display this file? */ 

/* MatchPattern ( ) is a dos. library function that 
** compares a matching pattern (parsed by the 
** ParsePattern ( ) DOS function) to a string and 
** returns true if they match. */ 
returnvalue = MatchPattern (pat , 

((struct AnchorPath *) obj ) ->ap_Inf o. f ib_FileName) 

/* we have to negate MatchPattern ()' s return value 
** because the file requester expects a zero for 
** a match not a TRUE value */ 
return ( (CPTR) (! returnvalue) ) ; 
break; 



Function Reference 



The following are brief descriptions of the ASL library functions. See the Amiga ROM Kernel Reference Manual: 
Includes and Autodocs for details on each function call. All of these functions require Release 2 or a later version 
of the operating system. 

Table 16-1: Functions for ASL Requesters 



Function 



Description 



AllocAslRequest() 

AllocAslRequestTags() 

AslRequest() 

AslRequestTags() 

FreeAslRequestQ 



Allocates an ASL font or file requester from a Tagltem array 
Same as AllocAslRequest() but accepts tags directly 
Displays an ASL requester with options set up in a Tagltem array 
Same as AslRequest() but accepts tags directly 
Deallocates an ASL requester created with AllocAslRequestQ 



Chapter 1 7 
Introduction To Exec 

The Multitasking Executive, better known as Exec, is the heart of the Amiga's operating system. All other 
systems in the Amiga rely on it to control multitasking, to manage the message-based interprocess 
communications system, and to arbitrate access to system resources. Because just about every software entity 
on the Amiga (including application programs) needs to use Exec in some way, every Amiga programmer has to 
have a basic understanding of its fundamentals. 

Multitasking 

A conventional micro-computer spends a lot of its time waiting for things to happen. It has to wait for such things 
as the user to push buttons on the keyboard or mouse, for data to come in through the serial port, and for data to 
go out to a disk drive. To make efficient use of the CPU's time, an operating system can have the CPU carry out 
some other task while it is waiting for such events to occur. 

A multitasking operating system reduces the amount of time it wastes, by switching to another program when the 
current one needs to wait for an event. A multitasking operating system can have several programs, or tasks, 
running at the same time. Each task runs independently of the others, without having to worry about what the 
other tasks are doing. From a task's point of view, it's as if each task has a computer all to itself. 

The Amiga's multitasking works by switching which task is currently using the CPU. A task can be a user's 
application program, or it can be a task that controls system resources (like the disk drives or the keyboard). Each 
task has a priority assigned to it. Exec will let the task with the highest priority use the CPU, but only if the task is 
ready to run. A task can be in one of three states: ready, sleeping, or running. 

A ready task is not currently using the CPU but is waiting to use the processor. Exec keeps a list of the tasks that 
are ready. Exec sorts this list according to task priority, so Exec can easily find the ready task with the highest 
priority. When Exec switches the task that currently has control of the CPU, it switches to the task at the top of 
this list. 

A sleeping task is not currently running and is waiting for some event to happen. When that event occurs, Exec 
will move the sleeping task into the list of ready tasks. 
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A running task is currently using the CPU. It will remain the current task until one of three things occur: 

A higher priority task becomes ready, so the OS preempts the current task and switches to the higher 
priority task. 

The currently running task needs to wait for an event, so it goes to sleep and Exec switches to the 
highest priority task in Exec's ready list. 

The currently running task has had control of the CPU for at least a preset time period called a quantum 
and there is another task of equal priority ready to run. In this case, Exec will preempt the current task 
for the ready one with the same priority. This is known as time-slicing. When there is a group of tasks of 
equal priority on the top of the ready list, Exec will cycle through them, letting each one use the CPU for 
a quantum (a slice of time). 

The terms "task" and "process" are often used interchangeably to represent the generic concept of task. On the 
Amiga, this terminology can be a little confusing because of the names of the data structures that are associated 
with Exec tasks. Each task has a structure associated with it called a Task structure (defined in <exec/tasks.h>). 
Most application tasks use a superset of the Task structure called a Process structure (defined in 
<dos/dosextens.h>). These terms are confusing to Amiga programmers because there is an important distinction 
between the Exec task with only a Task structure and an Exec task with a Process structure. 

The Process structure builds on the Task structure and contains some extra fields which allow the DOS library to 



associate an AmigaDOS environment to the task. Some elements of a DOS environment include a current input 
and output stream and a current working directory. These elements are important to applications that need to do 
standard input and output using functions like printf(). 

Exec only pays attention to the Task structure portion of the Process structure, so, as far as Exec is concerned, 
there is no difference between a task with a Task structure and a task with a Process structure. Exec considers 
both of them to be tasks. 

An application doesn't normally worry about which structure their task uses. Instead, the system that launches 
the application takes care of it. Both Workbench and the Shell (CLI) attach a Process structure to the application 
tasks that they launch. 



Dynamic Memory Allocation 



The Amiga has a soft machine architecture, meaning that all tasks, including those that are part of its operating 
system, do not use fixed memory addresses. As a result, any program that needs to use a chunk of memory 
must allocate that memory from the operating system. 

There are two functions on the Amiga for simple memory allocation: AllocMem() and AllocVec(). The two 
functions accept the same parameters, a ULONG containing the size of the memory block in bytes followed by 
32-bit specifier for memory attributes. Both functions return the address of a longword aligned memory block if 
they were successful or NULL if something went wrong. 

AllocVec() differs from AllocMem() in that it records the size of the memory block allocated so an application 
does not have to remember the size of a memory block it allocated. AllocVec() was introduced in Release 2, so it 
is not available to the 1 .3 developer. 
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Normally the bitmask of memory attributes passed to these functions will contain any of the following attributes 
(these flags are defined in <exec/memory.h>): 

MEMF_ANY 

This indicates that there is no requirement for either Fast or Chip memory. In this case, while there is 
Fast memory available, Exec will only allocate Fast memory. Exec will allocate Chip memory if there is 
not enough Fast memory. 

MEMF_CHIP 

This indicates the application wants a block of Chip memory, meaning it wants memory addressable by 
the Amiga custom chips. Chip memory is required for any data that will be accessed by custom chip 
DMA. This includes floppy disk buffers, screen memory, images that will be blitted, sprite data, copper 
lists, and audio data. If your application requires a block of Chip RAM, it must use this flag to allocate 
the Chip RAM. Otherwise, the application will fail on machines with expanded memory. 

MEMF_FAST 

This indicates a memory block outside of the range that the Amiga's custom chips can access. The 
"FAST" in MEMF_FAST has to do with the custom chips and the CPU trying to access the same 
memory at the same time. Because the custom chips and the CPU both have access to Chip RAM, the 
CPU may have to wait to access Chip RAM while some custom chip is reading or writing Chip RAM. In 
the case of Fast RAM, the custom chips do not have access to it, so the CPU does not have to contend 
with the custom chips access to Fast RAM, making CPU accesses to Fast RAM generally faster than 
CPU access to Chip RAM. 

Since the flag specifies memory that the custom chips cannot access, this flag is mutually exclusive 
with the MEMF_CHIP flag. If you specify the MEMF_FAST flag, your allocation will fail on Amigas that 
have only Chip memory. Use MEMF_ANY if you would prefer Fast memory. 

MEMF_PUBLIC 

This indicates that the memory should be accessible to other tasks. Although this flag doesn't do 
anything right now, using this flag will help ensure compatibility with possible future features of the 
OS (like virtual memory and memory protection). 



MEMF_CLEAR 

This indicates that the memory should be initialized with zeros. 

If an application does not specify any attributes when allocating memory, the system first looks for MEMF_FAST, 
then MEMF_CHIP. There are additional memory allocation flags for Release 2: MEM_LOCAL, 
MEMF_24BITDMA and MEMF_REVERSE. See the Exec Autodoc for AllocMem() in the Amiga ROM Kernel 
Reference Manual: Includes and Autodocs or the include file <exec/memory.h> for additional information on these 
flags. Use of these flags under earlier versions of the operating system will cause your allocation to fail. 

Make Sure You Have Memory. Always check the result of any memory allocation to be sure 
the type and amount of memory requested is available. Failure to do so will lead to trying to 
use an non-valid pointer. 

When an application is finished with a block of memory it allocated, it must return it to the operating system. 
There is a function to return memory for both the AllocMem() and the AllocVec() functions. FreeMem() releases 
memory allocated by AllocMem(). 
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It takes two parameters, a pointer to a memory block and the size of the memory block. FreeVec() releases 
memory allocated by AllocVec(). It takes only one parameter, a pointer to a memory block allocated by 
AllocVec(). The following example shows how to allocate and deallocate memory. 

APTR my_mem ; 

if (my_mem = AllocMem (100 , MEMF_ANY) ) 

{ 

/* Your code goes here */ 
FreeMem (my_mem, 100); 

} 

else 

{ 

/* couldn't get memory, exit with an error */ 

} 



Signals 



The Amiga uses a mechanism called signals to tell a task that some event occurred. Each task has its own set of 
32 signals, 16 of which are set aside for system use. When one task signals a second task, it asks the OS to set 
a specific bit in the 32-bit long word set aside for the second task's signals. 

Signals are what makes it possible for a task to go to sleep. When a task goes to sleep, it asks the OS to wake it 
up when a specific signal bit gets set. That bit is tied to some event. When that event occurs, that signal bit gets 
set. This triggers the OS into waking up the sleeping task. 

To go to sleep, a task calls a system function called Wait(). This function takes one argument, a bitmask that tells 
Exec which of the task's signal bits to "listen to". The task will only wake up if it receives one of the signals whose 
corresponding bit is set in that bitmask. For example, if a task wanted to wait for signals 17 and 19, it would call 
Wait() like this: 

mysignals = Wait(lL<<17 | 1L<<19) ; 

Wait() puts the task to sleep and will not return until some other task sets at least one of these two signals. When 
the task wakes up, mysignals will contain the bitmask of the signal or signals that woke up the task. It is possible 
for several signals to occur simultaneously, so any combination of the signals that the task Wait()ed on can occur. 
It is up to the waking task to use the return value from Wait() to figure out which signal or signals occurred. 

Looking for Break Keys 

One common usage of signals on the Amiga is for processing a user break. As was mentioned earlier, the OS 
reserves 16 of a tasks 32 signals for system use. Four of those 16 signals are used to tell a task about the 
Control-C, D, E, and F break keys. An application can process these signals. Usually, only CLI-based programs 
receive these signals because the Amiga's console handler is about the only user input source that sets these 



signals when it sees the Control-C, D, E, and F key presses. 

The signal masks for each of these key presses are defined in <dos/dos.h>: 

S IGBREAKF_CTRL_C 
S I GBREAKF_CTRL_D 
S I GBREAKF_CTRL_E 
S IGBREAKF_CTRL_F 

Note that these are bit masks and not bit numbers. 
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Processing Signals without WaitQing 

In some cases an application may need to process signals but cannot go to sleep to wait for them. For example, 
a compiler might want to check to see if the user hit Control-C, but it can't to go to sleep to check for the break 
because that will stop the compiler. In this case, the task can periodically check its own signal bits for the Ctrl-C 
break signal using the Exec library function, SetSignal(): 

oldsignals = ULONG SetSignal (ULONG newsignals, ULONG signalmask) ; 

Although SetSignal() can change a task's signal bits, it can also monitor them. The following fragment illustrates 
using SetSignal() to poll a task's signal bits for a Ctrl-C break: 

/* Get current state of signals */ 

signals = SetSignal (OL, OL) ; 

/* check for Ctrl-C */ 

if (signals & SIGBREAKF_CTRL_C) 

{ 

/* The Ctrl-C signal has been set, take care of processing it . . . */ 

/* . . .then clear the Ctrl-C signal */ 
SetSignal (OL, SIGBREAKF_CTRL_C) ; 
} 

If your task is waiting for signals, but is also waiting for other events that have no signal bit (such as input 
characters from standard input), you may need to use SetSignal(). In such cases, you must be careful not to poll 
in a tight loop (also known as busy-waiting). Busy-waiting hogs CPU time and degrades the performance of other 
tasks. One easy way around this is for a task to sleep briefly within its polling loop by using the timer.device, or 
the graphics function WaitTOFQ, or (if the task is a Process) the DOS library DelayQ) or WaitForChar() 
functions. 

For more information on signals, see the "Exec Signals" chapter of this manual. 

Interprocess Communications 

Another feature of the Amiga OS is its system of message-based interprocess communication. Using this system, 
a task can send a message to a message port owned by another task. Tasks use this mechanism to do things 
like trigger events or share data with other tasks, including system tasks. Exec's message system is built on top 
of Exec's task signaling mechanism. Most Amiga applications programming (especially Intuition programming) 
relies heavily upon this message-based form of interprocess communication. 

When one task sends a message to another task's message port, the OS adds the message to the port's 
message queue. The message stays in this queue until the task that owns the port is ready to check its port for 
messages. Typically, a task has put itself to sleep while it is waiting for an event, like a message to arrive at its 
message port. When the message arrives, the task wakes up to look in its message port. The messages in the 
message port's queue are arranged in first-in-first-out (FIFO) order so that, when a task receives several 
messages, it will see the messages in the order they arrived at the port. 

A task can use a message to share any kind of data with another task. This is possible because a task does not 
actually transmit an entire message, it only passes a pointer to a message. When a task creates a message 
(which can have many Kilobytes of data attached to it) and sends it to another task, the actual message does not 



move. 
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Essentially, when task A sends a message to task B, task A lends task B a chunk of its memory, the memory 
occupied by the message. After task A sends the message, it has relinquished that memory to task B, so it 
cannot touch the memory occupied by the message. Task B has control of that memory until task B returns the 
message to task A with the ReplyMsg() function. 

Let's look at an example. Many applications use Intuition windows as a source for user input. Without getting into 
too much detail about Intuition, when an application opens a window, it can set up the window so Intuition will 
send messages about certain user input events. Intuition sends these messages to a message port created by 
Intuition for use with this window. When an application successfully opens a window, it receives a pointer to a 
Window structure, which contains a pointer to this message port (Window.UserPort). For this example, we'll 
assume the window has been set up so Intuition will send a message only if the user clicks the window's close 
gadget. 

When Intuition opens the window in this example, it creates a message port for the task that opened the Window. 
Because the most common message passing system uses signals, creating this message port involves using one 
of the example task's 32 signals. The OS uses this signal to signal the task when it receives a message at this 
message port. This allows the task to sleep while waiting for a "Close Window" event to arrive. Since this simple 
example is only waiting for activity at one message port, it can use the WaitPort() function. WaitPort() accepts a 
pointer to a message port and puts a task to sleep until a message arrives at that port. 

This simple example needs two variables, one to hold the address of the window and the other to hold the 
address of a message. 

struct Message *mymsg; /*defined in <exec/ports .h> */ 

struct Window *mywin; /* defined in <intuition/intuition.h> */ 

/* at some point, this application would have successfully opened a */ 
/* window and stored a pointer to it in mywin. */ 

/* Here the application goes to sleep until the user clicks */ 

/* the window's close gadget. This window was set up so */ 

/* that the only time Intuition will send a message to this */ 

/* window's port is if the user clicks the window's close */ 

/* gadget. */ 

WaitPort (mywin- >UserPort) ; 

while (mymsg = GetMsg (mywin- >UserPort) ) 

/* process message now or copy information from message */ 

ReplyMsg (mymsg) ; 

/* Close window, clean up */ 

The Exec function GetMsgQ is used to extract messages from the message port. Since the memory for these 
messages belongs to Intuition, the example relinquishes each message as it finishes with them by calling 
ReplyMsgQ. Notice that the example keeps on trying to get messages from the message port until mymsg is 
NULL. This is to make sure there are no messages left in the message port's message queue. It is possible for 
several messages to pile up in the message queue while the task is asleep, so the example has to make sure it 
replies to all of them. Note that the window should never be closed within this GetMsg() loop because the while 
statement is still accessing the window's UserPort. 

Note that each task with a Process structure (sometimes referred to as a process) has a special process 
message port, Process.pr_MsgPort. This message port is only for use by Workbench and the DOS library itself. 
No application should use this port for its own use! 
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Waiting on Message Ports and Signals at the Same Time 

Most applications need to wait for a variety of messages and signals from a variety of sources. For example, an 
application might be waiting for Window events and also timer.device messages. In this case, an application 
must Wait() on the combined signal bits of all signals it is interested in, including the signals for the message 
ports where any messages might arrive. 

The MsgPort structure, which is defined in <exec/ports.h>, is what Exec uses to keep track of a message port. 
The UserPort field from the example above points to one of these structures. In this structure is a field called 
mp_SigBit, which contains the number (not the actual bit mask) of the message port's signal bit. To Wait() on 
the signal of a message port, WaitQ on a bit mask created by shifting 1 L to the left mp_SigBit times (1 L « 
msgport->mp_SigBit). The resulting bit mask can be OR'd with the bit masks for any other signals you wish to 
simultaneously wait on. 



Libraries and Devices 



One of the design goals for the Amiga OS was to make the system dynamic enough so that the OS could be 
extended and updated without effecting existing applications. Another design goal was to make it easy for 
different applications to be able to share common pieces of code. The Amiga accomplished these goals through 
a system of libraries. An Amiga library consists of a collection of related functions which can be anywhere in 
system memory (RAM or ROM). 

Devices are very similar to libraries, except they usually control some sort of I/O device and contain some extra 
standard functions. Although this section does not really discuss devices directly, the material here applies to 
them. For more information on devices, see the "Exec Device I/O" section of this manual or the Amiga ROM 
Kernel Reference Manual: Devices. 

An application accesses a library's functions through the library's jump, or vector, table. Before a task can use the 
functions of a particular library, it must first acquire the library's base pointer by calling the Exec OpenLibrary() 
function: 

struct Library *OpenLibrary ( UBYTE *libName, unsigned long mylibversion ); 

where MbName is a string naming the library and mylibversion is a version number for the library. The version 
number reflects a revision of the system software. The chart below lists the specific Amiga OS release versions 
that system libraries versions correspond to: 

This revision is obsolete. 

This was an NTSC only release and is obsolete. 
This was a PAL only release and is obsolete. 
This is the oldest revision of the OS still in use. 
This is almost the same as release 1.2 except it has 
an Autobooting expansion. library 
35 This is a special RAM-loaded version of the 1.3 revision, except 

that it knows about the A2024 display modes. No 
application should need this library unless they 
need to open an A2024 display mode under 1.3. 
36 Kickstart 2.0 - This is the original Release 2 revision that was 

initially shipped on early Amiga 3000 models. 
37 Kickstart 2.04 - This is the general Release 2 revision for all 

Amiga models. 

Introduction to Exec 435 

The OpenLibraryQ function looks for a library with a name that matches MbName and also with a version at least 
as high as mylibversion. For example, to open version 33 or greater of the Intuition library: 

IntuitionBase = OpenLibrary ( "intuition. library" , 33L) ; 

In this example, if version 33 or greater of the Intuition library is not available, OpenLibraryQ returns NULL. A 
version of zero in OpenLibrary() tells the OS to open any version of the library. Unless your code requires 
Release 2 features, it should specify a version number of 33 to remain backwards compatible with Kickstart 1 .2. 
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When OpenLibrary() looks for a library, it first looks in memory. If the library is not in memory, OpenLibrary() 
will look for the library on disk. If MbName is a library name with an absolute path (for example, 
"myapp:mylibs/mylib. library"), OpenLibraryQ will follow that absolute path looking for the library. If MbName is 
only a library name ("diskfont. library"), OpenLibrary() will look for the library in the directory that the LIBS: logical 
assign currently references. 

If OpenLibrary() finds the library on disk, it takes care of loading it and initializing it. As part of the initialization 
process, OpenLibraryQ dynamically creates a jump, or vector, table. There is a vector for each function in the 
library. Each entry in the table consists of a 680x0 jump instruction (JMP) to one of the library functions. The OS 
needs to create the vector table dynamically because the library functions can be anywhere in memory. 

After the library is loaded into memory and initialized, OpenLibrary() can actually "open" the library. It does this 
by calling the library's Open function vector. Every library has a standard vector set aside for an OPEN function 
so the library can set up any data or processes that it needs. Normally, a library's OPEN function increments its 
open count to keep track of how many tasks currently have the library opened. 

If any step of OpenLibraryQ fails, it returns a NULL value. If OpenLibraryQ is successful, it returns the address 
of the library base. The library base is the address of this library's Library structure (defined in 
<exec/libraries.h>). The Library structure immediately follows the vector table in memory. 

After an application is finished with a library, it must close it by calling CloseLibraryQ: 

void CloseLibrary (struct Library *libPtr) ; 

where MbPtr is a pointer to the library base returned when the library was opened with OpenLibraryQ. 

Library Vector Offsets (LVOs) 

After an application has successfully opened a library, it can start using the library's functions. To access a library 
function, an application needs the library base address returned by OpenLibraryQ and the function's Library 
Vector Offset (LVO). A function's LVO is the offset from the library's base address to the function's vector in the 
vector table, which means an LVO is a negative number (the vectors precedes the library base in memory). 
Application code enters a library function by doing a jump to subroutine (the 680x0 instruction JSR) to the proper 
negative offset (LVO) from the address of the library base. The library vector itself is a jump instruction (the 
680x0 instruction JMP) to the actual library function which is somewhere in memory. 

The only legal way for an application to access a library function is through the vector table. A function's LVO is 
always the same on every system and is not subject to change. A function's jump vector can, and does, change. 
Assuming that a function's jump vector is static is very bad, so don't do it. 
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Each library has four vectors set aside for library housekeeping: OPEN, CLOSE, EXPUNGE, and RESERVED. 
The OPEN vector points to a function that performs any custom initialization that this library needs, for example, 
opening other libraries that this library uses. The CLOSE function takes care of any clean up necessary when an 
application closes a library. The EXPUNGE vector points to a function that prepares the library for removal from 
the system. Normally the OS will not remove a library from memory until the system needs the memory the library 
occupies. The other vector, RESERVED, does not do anything at present and is reserved for future system use. 



Low Memory 
/ I \ 



Library Base_ 



JMP Function N (LVO= 



(N*6) 



JMP Function 6 (LVO=-36) 

JMP Function 5 (LVO=-30) 

JMP Function Reserved (LVO=-24) 

JMP Function Expunge (LV0=-18) 

JMP Function Close (LV0=-12) 

JMP Function Open (LV0=-6) 



Library Structure 



Data Area 



\|/ 
High Memory 

Figure 17-1 : An Exec Library Base in RAM 

Calling a Library Function 

To call a function in an Amiga system library, an assembler application must put the library's base address in 
register A6 and JSR to the function's LVO relative to A6. For example to call the Intuition function Display BeepQ: 

.a********************************************************************** 
xref _LVODisplayBeep 

move . 1 A6 , - (sp) ; save the current contents of A6 

; intuition. library must already be opened 

; and IntuitionBase must contain its base address 

move . 1 IntuitionBase, A6 ;put intuition base pointer in A6 
jsr _LVODisplayBeep (A6) ;call DisplayBeep ( ) 
move . 1 (SP)+, A6 /restore A6 to its original value 

IntuitionBase contains a pointer to the Intuition library's library base and _LVODisplayBeep is the LVO for the 
DisplayBeep() function. The external reference (xref) to _LVODisplayBeep is resolved from the linker library, 
amiga.lib. This linker library contains the LVO's for all of the standard Amiga libraries. Each LVO label starts with 
"_LVO" followed by the name of the library function. 

System Functions Do Not Preserve DO, D1, AO and At. If you need to preserve DO, D1 , AO, or 
A1 between calls to system functions, you will have to save and restore these values 
yourself. Amiga system functions use these registers as scratch registers and may write 
over the values your program left in these registers. The system functions preserve the 
values of all other registers. The result of a system function, if any, is returned in DO. 
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Figure 17-2: Calling a Library Function 



The example above is the actual assembly code generated by the macro named LINKLIB, which is defined in 
<exec/libraries.i>. The following fragment performs the same function as the fragment above: 

LINKLIB _LVODisplayBeep, IntuitionBase 

The amiga.lib linker library also contains small functions called stubs for each function in the Amiga OS. These 
stubs are normally for use with C code. 

Function parameters in C are normally pushed on the stack when a program calls a function. This presents a bit 
of a problem for the C programmer when calling Amiga OS functions because the Amiga OS functions expect 
their parameters to be in specific CPU registers. Stubs solve this problem by copying the parameters from the 
stack to the appropriate register. 

For example, the Autodoc for the Intuition library function MoveWindow() shows which registers MoveWindow() 
expects its parameters to be: 

MoveWindow (window, deltaX, deltaY); 
AO DO Dl 

The stub for MoveWindow() in amiga.lib has to copy window to register AO, deltaX to register DO, and deltaY to 
register D1 . 

The stub also copies Intuition library base into A6 and does an address-relative JSR to MoveWindow()'s LVO 
(relative to A6). The stub gets the library base from a global variable in your code called IntuitionBase. If you 
are using the stubs in amiga.libXo call Intuition library functions, you must declare a global variable called 
IntuitionBase. It must be called IntuitionBase because amiga.lib is specifically looking for the label 
IntuitionBase. 

/* This global declaration is here so amiga.lib can find 
the intuition. library base pointer. */ 
struct Library * IntuitionBase; 



void main (void) 
{ 

/* initialize IntuitionBase */ 
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if ( Intuit ionBase = OpenLibrary ( "intuition. library" , 33L) 
{ 



When this code gets linked with amiga.lib, the 
linker extracts the DisplayBeep ( ) stub routine from 
from amiga.lib and copies it into the executable. 
The stub copies whatever is in the variable 
IntuitionBase into A6 , and JSRs to 
_LVODisplayBeep (A6) . 



*/ 

DisplayBeep ( 



CloseLibrary ( IntuitionBase) 



} 

There is a specific label in amiga.libior the library base of every library in the Amiga operating system. The chart 
below lists the names of the library base pointer amiga.lib associates with each Amiga OS library. The labels for 
library bases are also in the "Function Offsets Reference" list in the Amiga ROM Kernel Reference Manual: 
Includes and Autodocs. 



Library Name 



Library Base Pointer Name 



asl . library 
commodities . library 
diskf ont . library 
dos . library 
exec . library 
expansion . library 
gadtools . library 
graphics . library 
icon. library 
if fparse . library 
intuition. library 
keymap . library 
layers . library 
mathf f p . library 
mathieeedoubbas . library 
mathieeedoubtrans . library 
mathieeesingbas . library 
mathieeesingtrans . library 
mathtrans . library 
rexxsys . library 
rexxsupport . library 
translator . library 
utility. library 
version .library 
workbench . 1 ibrary 
Library Name 



AslBase 

CxBase 

Diskf ontBase 

DOSBase 

SysBase 

Expans ionBase 

GadToolsBase 

GfxBase 

IconBase 

IFFParseBase 

IntuitionBase 

KeyMapBase 

LayersBase 

MathBase 

MathleeeDoubBasBase 

MathleeeDoubTransBase 

MathleeeSingBasBase 

MathleeeSingTransBase 

MathTransBase 

RexxSysBase 

RexxSupBase 

Trans latorBase 

UtilityBase 

(system private) 
WorkbenchBase 
Library Base Pointer Name 



* Automatically opened by the standard C startup module 



Table 17-1: Amiga.lib Library Base Labels 

The chart mentions that SysBase and DOSBase are already set up by the standard C startup module. For more 
information on the startup module, 

You May Not Need amiga.lib. Many C compilers provide ways of using pragmas or 
registerized parameters, so that a C program does not have to link with an amiga.lib stub to 
access a library function. See your compiler documentation for more details. 



Chapter 18 
Exec Libraries 



Exec maintains lists of libraries and devices. An Amiga library consists of a collection of related functions which 
can be anywhere in system memory (RAM or ROM). An Amiga device is very similar to an Amiga library, except 
that a device normally controls some sort of I/O hardware, and generally contains a limited set of standard 
functions which receive commands for controlling I/O. For more information on how to use devices for I/O, see 
the "Exec Device I/O" chapter of this book. 

Not for Beginners. This chapter concentrates on the internal workings of Execlibraries (and 
devices). Most application programmers will not to know the internals workings of libraries to 
program the Amiga. For an introduction to libraries and how to use them, see chapter one, 
"Introduction to Amiga System Libraries". 



What is a Library? 



A library consists of a group of functions somewhere in memory (ROM or RAM), a vector table, and a Library 
structure which can be followed by an optional private data area for the library. The library's base pointer (as 
returned by OpenLibraryQ) points to the library's Library data structure: 



struct Library 



struct 

UBYTE 

UBYTE 

UWORD 

UWORD 

UWORD 

UWORD 

APTR 

ULONG 

UWORD 



Node lib_Node; 

lib_Flags ; 

lib_pad; 

lib_NegSize; 

lib_PosSize; 

lib_Version; 

lib_Revision; 

lib_IdString; 

lib_Sum; 

lib_OpenCnt ; 



/* number of bytes before library */ 
/* number of bytes after library */ 



/* the checksum itself */ 

/* number of current opens */ 



/* A task is currently running a checksum */ 
/* on this library (system maintains this */ 
/* flag) */ 

/* One or more entries have been changed */ 
/* in the library code vectors used by */ 
/* SumLibrary (system maintains this flag)*/ 

/* A checksum fault should cause a system */ 
/* panic (library flag) */ 

/* A user has requested expunge but */ 
/* another user still has the library */ 
/* open (this is maintained by library) */ 
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Using a Library to Reference Data 

Most libraries (such as Intuition, graphics and Exec) have other data that follows the Library data structure in 
memory. Although it is not normally necessary, a program can use the library base pointer to access the Library 
structure and any custom library data. 

In general, the system's library base data is read-only, and should be directly accessed as little as possible, 
primarily because the format of the data may change in future revisions of the library. If the library provides 
functions to allow access to library data, use those instead. 



/* Meaning of the flag bits: 
#define LIBF_SUMMING (1 << 0) 
#define LIBF_CHANGED (1 << 1) 

#define LIBF_SUMUSED (1 << 2) 
#define LIBF DELEXP (1 << 3) 



Relationship of Libraries to Devices 

A device is a software specification for hardware control based on the Library structure. The structures of 
libraries and devices are so similar that the routine MakeLibrary() is used to construct both. 

Devices require the same initial four code vectors as a library, but must have two additional code vectors for 
beginning and terminating special device I/O commands. The I/O commands that devices are expected to 
perform, at minimum, are shown in the "Exec Device I/O" chapter. An example device is listed in the Amiga ROM 
Kernel Reference Manual: Devices. 

Minimum Subset of Library Vectors 

The first four code vectors of a library must be the following entries: 

OPEN 

is the entry point called by the function OpenLibraryQ. In most libraries, OPEN increments 
the library variable Mb_OpenCnt. This variable is also used by CLOSE and EXPUNGE. 

CLOSE 

is the entry point called by the function CloseLibraryQ. Itdecrements the library variable 
Mb_OpenCnt and may do a delayed EXPUNGE. 

EXPUNGE 

prepares the library for removal from the system. This often includes deallocating memory 
resources that were reserved during initialization. EXPUNGE not only frees the memory 
allocated for data structures, but also the areas reserved for the library node itself. 

RESERVED 

is a fourth function vector reserved for future use. It must always return zero. 

Changing the Contents of a Library 

The way in which an Amiga library is organized allows a programmer to change where the system looks for a 
library routine. Exec provides a function to do this: SetFunctionQ. The SetFunction() routine redirects a library 
function call to an application-supplied function. (Although it's not addressed here, SetFunction() can also be 
used on Exec devices.) For instance, the AmigaDOS command SetPatch uses SetFunctionQ to replace some 
OS routines with improved ones, primarily to fix bugs in ROM libraries. 
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The format of the SetFunction() routine is as follows: 

SetFunction( struct Library *lib, LONG funcOffset, APTR funcEntry) 

Al AO DO 

The lib argument is a pointer to the library containing the function entry to be changed. The funcOffset is the 
Library Vector Offset (negative) of the function and funcEntry is the address of the new function you want to 
replace it with. The SetFunction() routine replaces the entry in the library's vector table at the given Library 
Vector Offset with a new address that points to the new routine and returns the old vector address. The old 
address can be used in the new routine to call the original library function. 

Normally, programs should not attempt to "improve" library functions. Because most programmers do not know 
exactly what system library functions do internally, OS patches can do more harm than good. However, a 
legitimate use for SetFunction() is in a debugger utility. Using SetFunction(), a debugger could reroute system 
calls to a debugging routine. The debugging routine can inspect the arguments to a library function call before 
calling the original library function (if everything is OK). Such a debugger doesn't do any OS patching, it merely 
inspects. 

SetFunctionQ is for Advanced Users Only. It is very difficult to cleanly exit after performing 
SetFunctionQ because other tasks may be executing your code and also because 
additional SetFunctionQ's may have occurred on the same function. Also note that certain 
libraries (for example the V33 version of DOS library) and some individual library function 



vectors are of non-standard format and cannot be replaced via SetFunction(). 

Although useful, performing SetFunction() on a library routines poses several problems. If a second task 
performs SetFunctionQ on the same library entry, SetFunction() returns the address of the new routine to the 
second task, not the original system vector. In that case, the first task can no longer exit cleanly since that would 
leave the second task with an invalid pointer to a function which it could be relying on. 

You also need to know when it is safe to unload your replacement function. Removing it while another task is 
executing it will quickly lead to a crashed system. Also, the replacement function will have to be re-entrant, like all 
Exec library functions. 

Don't Do This! For those of you who might be thinking about writing down the ROM 
addresses returned by SetFunction() and using them in some other programs: Forget It. The 
address returned by SetFunctionQ is only good on the current system at the current time. 



Adding a Library 



Exec provides several ways to add your own libraries to the system library list. One rarely used way is to call 
LoadSeg() (a DOS library function) to load your library and then use the Exec MakeLibraryO and AddLibrary() 
functions to initialize your library and add it to the system. 

MakeLibraryO allocates space for the code vectors and data area, initializes the library node, and initializes the 
data area according to your specifications, returning to you a library base pointer. The base pointer may then be 
passed to AddLibrary() to add your library to the system. 

Another way to initialize and add a library or device to the system is through the use of a Resident structure or 
romtag (see <exec/resident.h>). A romtag allows you to place your library or device in a directory (default LIBS: 
for libraries, DEVS: for devices) and have the OS automatically load and initialize it when an application tries to 
open it with OpenLibrary() or OpenDevice(). 

Exec Libraries 443 

Two additional initialization methods exist for a library or device which is bound to a particular Amiga expansion 
board. The library or device (containing a romtag) may be placed in the SYS:Expansion drawer, along with an 
icon containing the Manufacturer and Product number of the board it requires. If the startup-sequence 
BindDrivers command finds that board in the system, it will load and initialize the matching Expansion drawer 
device or library. In addition, since 1 .3, the Amiga system software supports ROM drivers on expansion boards. 
See the "Expansion Library" chapter for additional information on ROM drivers and Expansion drawer drivers. 
The sample device code in the Amiga ROM Kernel Reference Manual: Devices volume of this manual set may be 
conditionally assembled as an Expansion drawer driver. 

Resident (Romtag) Structure 



A library or device with a romtag should start with moveq 
execute the file), followed by a Resident structure: 



#-i, do (to safely return an error if a user tries to 



STRUCTURE RT, 

UWORD RT_MATCHWORD 

APTR RT_MATCHTAG 

APTR RT_ENDSKIP 

UBYTE RT_FLAGS 

UBYTE RTJVERSION 

UBYTE RTJTYPE 

BYTE RT_PRI 

APTR RT_NAME 

APTR RT_IDSTRING 

APTR RT_INIT 

LABEL RT SIZE 



romtag identifier (==$4AFC) 

pointer to the above UWORD (RT_MATCHWORD) 

usually ptr to end of your code 

usually RTF_AUTOINIT 

release version number (for example: 37) 

type of module (NT_LIBRARY) 

initialization priority (for example: 0) 

pointer to node name ( "my . library" ) 

pointer to id string ("name ver.rev (date) 

pointer to init code or AUTOINIT tables 

size of a Resident structure (romtag) 



If you wish to perform MakeLibraryO and AddLibraryQ yourself, then your RT_FLAGS will not include 
RTF_AUTOINIT, and RT_INIT will be simply be a pointer to your own initialization code. To have Exec 
automatically load and initialize the library, set the RTF_AUTOINIT flag in the Resident structure's RT_FLAGS 
field, and point RTJNIT to a set four longwords containing the following: 



dataSize 

This is the size of your library data area, i.e., the combined size of the standard Library node structure 
plus your own library-specific data. 

vectors 

This is a pointer to a table of pointers to your library's functions, terminated with a -1 . If the first word of 
the table is -1 , then the table is interpreted as a table of words specifying the relative displacement of 
each function entry point from the start of the table. Otherwise it is treated as a table of longword 
address pointers to the functions, vectors must specify a valid table address. 

structure 

This parameter points to the base of an lnitStruct() data region. That is, it points to the first location 
within a table that the lnitStruct() routine can use to initialize your Library node structure, 
library-specific data, and other memory areas. lnitStruct() will typically be used to initialize the data 
segment of the library, perhaps forming data tables, task control blocks, I/O control blocks, etc. If this 
entry is a 0, then lnitStruct() is not called. 

InitFunction 

This points to a routine that is to be executed after the library (or device) node has been allocated and 
the code and data areas have been initialized. When the routine is called, the base address of the 
newly created library is passed in DO. If initFunction is zero, no initialization routine is called. 

Complete source code for an RT_AUTOINIT library may be found in the appendix C of this book. 
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Chapter 19 
Exec Device I/O 



The Amiga system devices are software engines that provide access to the Amiga hardware. Through these 
devices, a programmer can operate a modem, spin a disk drive motor, time an event, and blast a trumpet sound 
in stereo. Yet, for all that variety, the programmer uses each device in the same manner. 



What is a Device? 



An Amiga device is a software module that accepts commands and data and performs I/O operations based on 
the commands it receives. In most cases, it interacts with either internal or external hardware, (the exceptions are 
the clipboard device and ramdrive device which simply use memory). Generally, an Amiga device runs as a 
separate task which is capable of processing your commands while your application attends to other things. 

Table 19-1 : Amiga System Devices 



Amiga Device 


Purpose 


Audio 


Controls the use of the audio hardware. 


Clipboard 


Manages the cutting and pasting of common data blocks 


Console 


Provides the line-oriented user interface. 


Gameport 


Controls the two mouse/joystick ports. 


Input 


Processes input from the gameport and keyboard devices. 


Keyboard 


Controls the keyboard. 


Narrator 


Produces the Amiga synthesized speech. 


Parallel 


Controls the parallel port. 


Printer 


Converts a standard set of printer control codes to printer specific codes. 


SCSI 


Controls the Small Computer Standard Interface hardware. 


Serial 


Controls the serial port. 


Timer 


Provides timing functions to measure time intervals and send interrupts. 


Trackdisk 


Controls the Amiga floppy disk drives. 



The philosophy behind the devices is that I/O operations should be consistent and uniform. You print a file in the 
same manner as you play an audio sample, i.e., you send the device in question a WRITE command and the 
address of the buffer holding the data you wish to write. 
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The result is that the interface presented to the programmer is essentially device independent and accessible 
from any computer language. This greatly expands the power the Amiga brings to the programmer and, 
ultimately, to the user. 

Devices support two types of commands: Exec standard commands like READ and WRITE, and device specific 
commands like the trackdisk device MOTOR command which controls the floppy drive motor, and the keyboard 
device READMATRIX command which returns the state of each key on the keyboard. You should keep in mind, 
however, that supporting standard commands does not mean that all devices execute them in exactly the same 
manner. 

This chapter contains an introduction to the Exec and amiga.lib functions that are used when accessing Amiga 
devices. Consult the Amiga ROM Kernel Manual: Devices volume for chapters on each of the Amiga devices and 
the commands they support. In addition, the Amiga ROM Kernel Reference Manual: Includes and Autodocs 
contains Autodocs summarizing the commands of each device, and listings of the device include files. Both are 
very useful manuals to have around when you are programming the devices. 



Accessing a Device 



Accessing a device requires obtaining a message port, allocating memory for a specialized message packet 
called an I/O request, setting a pointer to the message port in the I/O request, and finally, establishing the link to 



the device itself by opening it. An example of how to do this will be provided later in this chapter. 

Creating a Message Port 

When a device completes the command in a message, it will return the message to the message port specifed as 
the reply port in the message. A message port is obtained by calling the CreateMsgPortQ or CreatePort() 
function. You must delete the message port when you are finished by calling the DeleteMsgPort() or 
DeletePort() function. 

If your application needs to be compatible with pre-V36 versions of the operating system, use the amiga.lib 
functions CreatePort() and DeletePortQ ; if you require V36 or higher, you may use the Exec ROM functions 
CreateMsgPort() and DeleteMsgPort(). 

Creating an 10 Request 

The I/O request is used to send commands and data from your application to the device. The I/O request 
consists of fields used to hold the command you wish to execute and any parameters it requires. You set up the 
fields with the appropriate information and send it to the device by using Exec I/O functions. Different Amiga 
devices often require different I/O request structures. These structures all start with a simple lORequest or 
loStdReq structure (see <exec/io.h>) which may be followed by various device-specific fields. Consult the 
Autodoc and include file for each device to determine the type and size I/O request required to access the device. 

I/O request structures are commonly created and deleted with the amiga.lib functions CreateExtlOQ with 
DeleteExtlOQ. These amiga.lib functions are compatible with Release 2 and previous versions of the operating 
system. Applications that already require V37 for other reasons may instead use the new V37 ROM Exec 
functions CreatelORequestQ and DeletelORequest(). Any size and type of I/O request may be created with 
these functions. 
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Alternately, I/O requests can be created by declaring them as structures initialized to zero, or by dynamically 
allocating cleared public memory for them, but in these cases you will be responsible for the lORequest structure 
initializations which are normally handled by the above functions. The message port pointer in the I/O request 
tells the device where to respond with messages for your application. You must set a pointer to the message port 
in the I/O request if you declare it as a structure or allocate memory for it using AllocMem(). 

Opening a Device 

The device is opened by calling the OpenDevice() function. In addition to establishing the link to the device, 
OpenDevice() also initializes fields in the I/O request. OpenDevice() has this format: 

return = OpenDevice (device_name, unit_number, (struct lORequest *) lORequest, flags) 

device_name is one of the following NULL-terminated strings for system devices: 
Audio. device Parallel. device Clipboard.device 
Printer. device Console. device scsi. device 
Gameport.device Serial.device Input.device 
Timer.device Keyboard. device Trackdisk.device 
Narrator.device 

unit_number is refers to one of the logical units of the device. Devices with one unit always use unit 0. 
Multiple unit devices like the trackdisk device and the timer device use the different units for specific 
purposes. 

lORequest is the structure discussed above. Some of the devices have their own I/O requests defined 
in their include files and others use standard I/O requests, (lOStdReq). Refer to the Amiga ROM Kernel 
Reference Manual: Devices for more information. 

flags are bits set to indicate options for some of the devices. This field is set to zero for devices which 
don't accept options when they are opened. The flags for each device are explained in the Amiga ROM 
Kernel Reference Manual: Devices. 

return is an indication of whether the OpenDevice() was successful with zero indicating success. Never 



assume that a device will successfully open. Check the return value and act accordingly. 

Zero Equals Success for OpenDeviceQ. Unlike most Amiga system functions, OpenDevice() 
returns zero for success and a device-specific error value for failure. 



Using a Device 



Once a device has been opened, you use it by passing the I/O request to it. When the device processes the I/O 
request, it acts on the information the I/O request contains and returns a reply message, i.e., the I/O request, to 
the message port when it is finished. The I/O request is passed to a device using one of three functions, DolO(), 
SendlO() and BeginlO(). They take only one argument: the I/O request you wish to pass to the device. 

DolOQ is a synchronous function. It will not return until the device has finished with the I/O request. 
DolO() will wait, if necessary, for the request to complete, and will remove (GetMsgO) any reply 
message from the message port. 
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SendlO() is an asynchronous function. It can return immediately, but the I/O operation it initiates may 
take a short or long time. SendIO is normally used when your application has other work to do while the 
I/O request is being acted upon, or if your application wishes to allow the user to cancel the I/O. Using 
SendlOQ requires that you wait on or check for completion of the request, and remove the completed 
request from the message port with GetMsgQ. 

BeginlO() is commonly used to control the QuicklO bit when sending an I/O request to a device. When 
the QuicklO flag (IOF_QUICK) is set in the I/O request, a device is allowed to take certain shortcuts in 
performing and completing a request. If the request can complete immediately, the device will not return 
a reply message and the QuicklO flag will remain set. If the request cannot be completed immediately, 
the QUICKJO flag will be clear. DolO() normally requests QuicklO; SendlO() does not. 

An I/O request typically has three fields set for every command sent to a device. You set the command itself in 
the io_Command field, a pointer to the data for the command in the io_Data field, and the length of the data in 
the io_Length field. 

SerialIO->IOSer . io_Length = sizeof (ReadBuf f er) ; 
SerialIO->IOSer . io_Data = ReadBuf fer; ; 
SerialIO->IOSer. io_Command = CMD_READ; 
SendIO ( (struct IORequest *) SeriallO) ; 

Commands consist of two parts (separated by an underscore, all in upper case): a prefix and the command word. 
The prefix indicates whether the command is an Exec or device specific command. All Exec standard commands 
have "CMD" as the prefix. They are defined in the include file <exec/io.h>. 

Table 19-2: Standard Exec Device Commands 



CMD_READ CMD_START CMD_UPDATE CMD_CLEAR 

CMD WRITE CMD STOP CMD FLUSH CMD RESET 



You should not assume that a device supports all standard Exec device commands. Always check the 
documentation before attempting to use one of them. Device-specific command prefixes vary with the device. 



Table 19-3: System Device Command Prefixes 



Device 


Prefix 


Example 


Audio 


ADCMD 


ADCMD ALLOCATE 


Clipboard 


CBD 


CBD POST 


Console 


CD 


CD ASKKEYMAP 


Gameport 


GPD 


GPD SETCTYPE 


Input 


IND 


IND SETMPORT 


Keyboard 


KBD 


KBD_READMATRIX 


Narrator 


no device specific commands 


- 


Parallel 


PDCMD 


PDCMD QUERY 


Printer 


PRD 


PRD PRTCOMMAND 


SCSI 


HD 


HD SCSICMD 


Serial 


SDCMD 


SDCMD BREAK 


Timer 


TR 


TR ADDREQUEST 


Trackdisk 


TD and ETD 


TD MOTOR/ETD MOTOR 
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Each device maintains its own I/O request queue. When a device receives an I/O request, it either processes the 
request immediately or puts it in the queue because one is already being processed. After an I/O request is 
completely processed, the device checks its queue and if it finds another I/O request, begins to process that 
request. 

Synchronous Vs. Asynchronous Requests 



As stated above, you can send I/O requests to a device synchronously or asynchronously. The choice of which to 
use is largely a function of your application. 

Synchronous requests use the DolOQ function. DolOQ will not return control to your application until the I/O 
request has been satisfied by the device. The advantage of this is that you don't have to monitor the message 
port for the device reply because DolO() takes care of all the message handling. The disadvantage is that your 
application will be tied up while the I/O request is being processed, and should the request not complete for some 
reason, DolO() will not return and your application will hang. 

Asynchronous requests use the SendlO() and BeginlO() functions. Both return to your application almost 
immediately after you call them. This allows you to do other operations, including sending more I/O requests to 
the device. Note that any additional I/O requests you send must use separate I/O request structures. Outstanding 
I/O requests are not available for re-use until the device is finished with them. 

Do Not Touch! When you use SendlOQ or BeginlOQ, the I/O request you pass to the device 
and any associated data buffers should be considered read-only. Once you send it to the 
device, you must not modify it in any way until you receive the reply message from the device 
or abort the request. 

Sending multiple asynchronous I/O requests to a device can be tricky because devices require them to be unique 
and initialized. This means you can't use an I/O request that's still in the queue, but you need the fields which 
were initialized in it when you opened the device. The solution is to copy the initialized I/O request to another I/O 
request(s) before sending anything to the device. 

Regardless of what you do while you are waiting for an asynchronous I/O request to return, you need to have 
some mechanism for knowing when the request has been done. There are two basic methods for doing this. 

The first involves putting your application into a wait state until the device returns the I/O request to the message 
port of your application. You can use the WaitlOQ, WaitQ or WaitPort() function to wait for the return of the I/O 
request. It is important to note that all of the above functions and also DolOQ may Wait() on the message reply 
port's mp_SigBit. For this reason, the task that created the port must be the same task the waits for completion 
of the I/O. There are three ways to wait: 

WaitlOQ not only waits for the return of the I/O request, it also takes care of all the message handling 
functions. This is very convenient, but you can pay for this convenience: your application will hang if the 
I/O request does not return. 



Wait() waits for a signal to be sent to the message port. It will awaken your task when the signal arrives, 
but you are responsible for all of the message handling. 

WaitPort() waits for the message port to be non-empty. It returns a pointer to the message in the port, 
but you are responsible for all of the message handling. 
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The second method to detect when the request is complete involves using the ChecklO() function. ChecklO() 
takes an I/O request as its argument and returns an indication of whether or not it has been completed. When 
ChecklOQ returns the completed indication, you will still have to remove the I/O request from the message port. 

I/O Request Completion 

A device will set the io_Error field of the I/O request to indicate the success or failure of an operation. The 
indication will be either zero for success or a non-zero error code for failure. There are two types of error codes: 
Exec I/O and device specific. Exec I/O errors are defined in the include file <exec/errors.h>; device specific errors 
are defined in the include file for each device. You should always check that the operation you requested was 
successful. 

The exact method for checking io_Error can depend on whether you use DolO() or SendlOQ. In both cases, 
io_Error will be set when the I/O request is returned, but in the case of DolO(), the DolO() function itself returns 
the same value as io_Error. This gives you the option of checking the function return value: 

SerialIO->IOSer . io_Length = sizeof (ReadBuf f er) ; 
SerialIO->IOSer . io_Data = ReadBuf fer; : 
SerialIO->IOSer. io_Command = CMD_READ; 
if (DoIO ( (struct IORequest *)SerialIO) 

printf ( "Read failed. Error: %ld\n" , SerialIO->IOSer . io_Error) ; 

Or you can check io_Error directly: 

SerialIO->IOSer . io_Length = sizeof (ReadBuf fer) ; 
SerialIO->IOSer . io_Data = ReadBuf fer, • 
SerialIO->IOSer . io_Command = CMD_READ; 
DoIO((struct IORequest *) SeriallO) ; 
if (SerialIO->IOSer . io_Error) 

printf ("Read failed. Error: %ld\n" , SerialIO->IOSer . io_Error) ; 

Keep in mind that checking io_Error is the only way that I/O requests sent by SendlOQ can be checked. Testing 
for a failed I/O request is a minimum step, what you do beyond that depends on your application. In some 
instances, you may decide to resend the I/O request and in others, you may decide to stop your application. One 
thing you'll almost always want to do is to inform the user that an error has occurred. 

Exiting The Correct Way. If you decide that you must prematurely end your application, you 
should deallocate, release, give back and let go of everything you took to run the application. 
In other words, you should exit gracefully. 

Closing the Device 

You end device access by reversing the steps you did to access it. This means you close the device, deallocate 
the I/O request memory and delete the message port. In that order! 

Closing a device is how you tell Exec that you are finished using a device and any associated resources. This 
can result in housecleaning being performed by the device. However, before you close a device, you might have 
to do some housecleaning of your own. 
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A device is closed by calling the CloseDevice() function. The CloseDevice() function does not return a value. It 
has this format: 

CloseDevice (IORequest) ; 



where lORequest is the I/O request used to open the device. 

You should not close a device while there are outstanding I/O requests, otherwise you can cause major and minor 
problems. Let's begin with the minor problem: memory. If an I/O request is outstanding at the time you close a 
device, you won't be able to reclaim the memory you allocated for it. 

The major problem: the device will try to respond to the I/O request. If the device tries to respond to an I/O 
request, and you've deleted the message port (which is covered below), you will probably crash the system. 

One solution would be to wait until all I/O requests you sent to the device return. This is not always practical if 
you've sent a few requests and the user wants to exit the application immediately. 

In that case, the only solution is to abort and remove any outstanding I/O requests. You do this with the functions 
AbortlO() and WaitlO(). They must be used together for cleaning up. AbortlO() will abort an I/O request, but will 
not prevent a reply message from being sent to the application requesting the abort. WaitlO() will wait for an I/O 
request to complete and remove it from the message port. This is why they must be used together. 

Be Careful With AbortlOQ! Do not AbortlO() an I/O request which has not been sent to a 
device. If you do, you may crash the system. 

Ending Device Access 

After the device is closed, you must deallocate the I/O request memory. The exact method you use depends on 
how you allocated the memory in the first place. For AllocMem() you call FreeMem(), for CreateExtlOQ you call 
DeleteExtlOQ, and for CreatelORequestQ you call DeletelORequestQ. If you allocated the I/O request memory 
at compile time, you naturally have nothing to free. 

Finally, you must delete the message port you created. You delete the message port by calling DeleteMsgPort() 
if you used CreateMsgPort(), or DeletePort() if you used CreatePort(). 

Here is the checklist for gracefully exiting: 

Abort any outstanding I/O requests with AbortlOQ. 

Wait for the completion of any outstanding or aborted I/O requests with WaitlO(). 

Close the device with CloseDeviceQ. 

Release the I/O request memory with either DeletelORequestQ, DeleteExtlO() or FreeMem() (as 
appropriate). 

Delete the message port with DeleteMsgPort() or DeletePort(). 
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Devices With Functions 



Some devices, in addition to their commands, provide library-style functions which can be directly called by 
applications. These functions are documented in the device specific FD files and Autodocs of the Amiga ROM 
Kernel Reference Manual: Includes and Autodocs, and in the Devices volume of this manual set. 

Devices with functions behave much like Amiga libraries, i.e., you set up a base address pointer and call the 
functions as offsets from the pointer. See the "Exec Libraries" chapter for more information. 

The procedure for accessing a device's functions is as follows: 

Declare the device base address variable in the global data area. The correct name for the base address 
can be found in the device's FD file. 

Create a message port data structure. 

Create an I/O request data structure. 



Call OpenDevice(), passing the I/O request. If OpenDevice() is successful (returns 0), the address of 
the device base may be found in the io_Device field of the I/O request structure. Consult the include file 
for the structure you are using to determine the full name of the io_Device field. The base address is 
only valid while the device is open. 

Set the device base address variable to the pointer returned in the io_Device field. 

We will use the timer device to illustrate the above method. The name of the timer device base address is listed 
in its FD file as TimerBase. 

#include <devices/timer .h> 

struct Library *TimerBase; /* device base address pointer */ 

struct MsgPort *TimerMP; /* message port pointer */ 

struct timerequest *TimerIO; /* I/O request pointer */ 

if (TimerMP=CreatePort (NULL, NULL) ) /* Create the message port. */ 

{ 

/* Create the I/O request. */ 

if ( TimerlO = (struct timerequest *) 

CreateExtIO (TimerMP, sizeof (struct timerequest) ) 

{ 

/* Open the timer device. */ 

if ( ! (OpenDevice (TIMERNAME,UNIT_MICROHZ, TimerlO, 0) ) ) 

{ 

/* Set up pointer for timer functions. */ 

TimerBase = (struct Library *) TimerlO- >tr_node . io_Device; 

/* Use timer device library-style functions such as CmpTime ( ) ...*/ 
CloseDevice (TimerlO) ; 
/* Close the timer device. */ 

} 
else 

printf ( "Error : Could not open %s\n" , TIMERNAME) ; 

} 

else 

printf ( "Error : Could not create I/O request\n"); 

} 

else 

printf ( "Error : Could not create message port\n"); 
} 
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Using An Exec Device 

The following short example demonstrates use of an Amiga device. The example opens the serial. device and 
then demonstrates both synchronous (DolOQ) and asynchronous (SendlOQ) use of the serial command 
SDCMD_QUERY. This command is used to determine the status of the serial device lines and registers. The 
example uses the backward compatible amiga.lib function for creation and deletion of the message port and I/O 
request. 

;/* DeviceUse.c - Execute me to compile me with SAS C 5.10 

LC -bl -cfistq -v -y -j73 DeviceUse.c 

Blink FROM LIB : c . o, DeviceUse . o TO DeviceUse LIBRARY LIB : LC . lib, LIB : Amiga . lib 

quit 

/* The following short example demonstrates use of an Amiga device. The */ 
/* example opens the serial .device and then demonstrates both */ 

/* synchronous (DoIOO) and asynchronous (SendlOO) use of the serial */ 
/* command SDCMD_QUERY. This command is used to determine the status of */ 
/* the serial device lines and registers. The example uses the backward */ 
/* compatible amiga.lib functions for creation and deletion of the */ 
/* message port and I/O request. */ 



/* DeviceUse.c - an example of using an Amiga device (here, serial device) */ 

/* - attempt to create a message port with CreatePortO (from amiga.lib) */ 

/* - attempt to create the I/O request with CreateExtIO ( ) (from amiga.lib) */ 

/* - attempt to open the serial device with Exec OpenDeviceO */ 

/* */ 

/* If successful, use the serial command SDCMD_QUERY, then reverse our steps. */ 

/* If we encounter an error at any time, we will gracefully exit. Note that */ 

/* applications which require at least V37 OS should use the Exec functions */ 

/* CreateMsgPort () /DeleteMsgPort () and CreatelORequest ( ) /DeletelORequest ( ) */ 

/* instead of the similar amiga.lib functions which are used in this example. */ 

#include <exec/types .h> 
#include <exec/memory .h> 
#include <exec/io.h> 
#include <devices/serial .h> 

#include <clib/exec_protos .h> /* Prototypes for Exec library functions */ 
#include <clib/alib_protos .h> /* Prototypes for amiga.lib functions */ 

#include <stdio.h> 

#ifdef LATTICE 

int CXBRK(void) { return(O); } /* Disable SAS CTRL/C handling */ 

int chkabort (void) { return(O); } /* really */ 

#endif 

void main (void) 

{ 

struct MsgPort *serialMP; /* for pointer to our message port */ 

struct IOExtSer *serialIO; /* for pointer to our I/O request */ 

struct IOExtSer *reply; /* for use with GetMsg */ 

if (serialMP=CreatePort (NULL, NULL) ) /* Create the message port. */ 

{ 

/* Create the I/O request. Note that <devices/serial .h> defines the type */ 
/* of IORequest required by the serial device--an IOExtSer. Many devices */ 
/* require specialized extended 10 requests which start with an embedded */ 
/* struct IORequest. The generic Exec and amiga.lib device 10 functions */ 
/* are prototyped for IORequest, so some pointer casting is necessary. */ 

if (seriallO = (struct IOExtSer *) CreateExtIO (serialMP, sizeof (struct IOExtSer))) 

{ 

/* Open the serial device (non-zero return value means failure here) . */ 
if (OpenDevice( SERIALNAME, 0, (struct IORequest *)serialI0, OL) ) 

printf ( "Error : %s did not open\n" , SERIALNAME) ; 
else 

{ 

/* Device is open */ /* DoIO - demonstrates synchronous */ 

serialIO->IOSer . io_Command = SDCMD_QUERY ; /* device use, returns error or . */ 
if (DoIO ( (struct IORequest *)serialI0)) 

printf ( "Query failed. Error - %d\n" , serialI0->I0Ser . io_Error) ; 
else 

/* Print serial device status - see include file for meaning */ 
/* Note that with DoIO, the Wait and GetMsg are done by Exec */ 
printf ( "Serial device status: $%x\n\n" , serialIO->io_Status) ; 

serialI0->I0Ser . io_Command = SDCMD_QUERY; /* SendIO - demonstrates asynchronous */ 
SendIO ( (struct IORequest *)serialIO); /* device use (returns immediately). */ 

/* We could do other things here while the query is being done. */ 

/* And to manage our asynchronous device 10: */ 

/* - we can ChecklO (seriallO) to check for completion */ 

/* - we can AbortIO (seriallO) to abort the command */ 

/* - we can WaitPort (serialMP) to wait for any serial port reply */ 

/* OR we can WaitIO (seriallO) to wait for this specific 10 request */ 

/* OR we can Wait(lL << serialMP_>mp_SigBit) for reply port signal */ 

Wait(lL << serialMP- >mp_SigBit ) ; 

whiletreply = (struct IOExtSer *) GetMsg (serialMP) ) 

{ /* Since we sent out only one seriallO request the while loop is */ 
/* not really needed--we only expect one reply to our one query */ 
/* command, and the reply message pointer returned by GetMsg () */ 



/* will just be another pointer to our one seriallO request. */ 
/* With WaitO or WaitPortO, you must GetMsgO the message. */ 
if (reply- >IOSer. io_Error) 

printf ( "Query failed. Error - %d\n" , reply->IOSer . io_Error) ; 
else 

printf ( "Serial device status: $%x\n\n" , reply- >io_Status) ; 

} 

CloseDevice ( (struct IORequest *) seriallO) ; /* Close the serial device. 



} 

DeleteExtIO (seriallO) ; 



/* Delete the I/O request. 



} 

else printf ( "Error : Could create I/O request\n" ) ; /* Inform user that the I/O 

/* request could be created. 
DeletePort (serialMP) ; /* Delete the message port. 



*/ 

*/ 

*/ 
*/ 
*/ 



else printf ( "Error : Could not create message port\n"); /* Inform user that the message*/ 

/* port could not be created. */ 



Function Reference 



The following chart gives a brief description of the Exec functions that control device I/O. See the Amiga ROM 
Kernel Reference Manual: Includes and Autodocs for details about each call. 

Table 19-4: Exec Device I/O Functions 



Exec Device I/O Function 


Description 


CreatelORequest() 


Create an IORequest structure (V36). 


DeletelORequest() 


Delete an IORequest created by CreatelORequestQ (V36). 


OpenDevice() 


Gain access to an Exec device. 


CloseDevice() 


Close Exec device opened with OpenDevice(). 


DolO() 


Perform a device I/O command and wait for completion. 


SendlO() 


Initiate an I/O command. Do not wait for it to complete. 


ChecklO() 


Get the status of an IORequest. 


WaitlO() 


Wait for completion of an I/O request. 


AbortlO() 

1 


Attempt to abort an I/O request that is in progress. 



Table 19-5: Exec Support Functions in amiga.lib 



Function 



Description 



BeginlO() 

CreateExtlO() 

DeleteExtlO() 



Initiate an asynchronous device I/O request. 

Create an IORequest data structure. 

Free an IORequest structure allocated by CreateExtlOQ. 
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Chapter 20 

Exec Memory Allocation 

Exec manages all of the free memory currently available in the system. Using linked list structures, Exec keeps 
track of memory and provides the functions to allocate and access it. 

When an application needs some memory, it can either declare the memory statically within the program or it can 
ask Exec for some memory. When Exec receives a request for memory, it looks through its list of free memory 
regions to find a suitably sized block that matches the size and attributes requested. 

Memory Functions 

Normally, an application uses the AllocMem() function to ask for memory: 

APTR AllocMem(ULONG byteSize, ULONG attributes) ; 

The byteSize argument is the amount of memory the application needs and attributes is a bit field which 
specifies any special memory characteristics (described later). If AllocMem() is successful, it returns a pointer to 
a block of memory. The memory allocation will fail if the system cannot find a big enough block with the 
requested attributes. If AllocMem() fails, it returns NULL. 

Because the system only keeps track of how much free memory is available and not how much is in use, it has no 
idea what memory has been allocated by any task. This means an application has to explicitly return, or 
deallocate, any memory it has allocated so the system can return that memory to the free memory list. If an 
application does not return a block of memory to the system, the system will not be able to reallocate that memory 
to some other task. That block of memory will be lost until the Amiga is reset. If you are using AllocMem() to 
allocate memory, a call to FreeMem() will return that memory to the system: 

void FreeMem(APTR mymemblock, ULONG byteSize); 

Here mymemblock is a pointer to the memory block the application is returning to the system and byteSize is the 
same size that was passed when the memory was allocated with AllocMem(). 

Unlike some compiler memory allocation functions, the Amiga system memory allocation functions return memory 
blocks that are at least longword aligned. This means that the allocated memory will always start on an address 
which is at least evenly divisible by four. This alignment makes the memory suitable for any system structures or 
buffers which require word or longword alignment, and also provides optimal alignment for stacks and memory 
copying. 
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Memory Attributes 

When asking the system for memory, an application can ask for memory with certain attributes. The currently 
supported flags are listed below. Flags marked "V37" are new memory attributes for Release 2. Allocations which 
specify these new bits may fail on earlier systems. 

MEMF_ANY 

This indicates that there is no requirement for either Fast or Chip memory. In this case, while there is 
Fast memory available, Exec will only allocate Fast memory. Exec will allocate Chip memory if there is 
not enough Fast memory. 

MEMF_CHIP 

This indicates the application wants a block of chip memory, meaning it wants memory addressable by 
the Amiga custom chips. Chip memory is required for any data that will be accessed by custom chip 
DMA. This includes screen memory, images that will be blitted, sprite data, copper lists, and audio 
data, and pre-V37 floppy disk buffers. If this flag is not specified when allocating memory for these 
types of data, your code will fail on machines with expanded memory. 



MEMF_FAST 

This indicates a memory block outside of the range that the special purpose chips can access. "FAST" 
means that the special-purpose chips do not have access to the memory and thus cannot cause 
processor bus contention, therefore processor access will likely be faster. Since the flag specifies 
memory that the custom chips cannot access, this flag is mutually exclusive with the MEMF_CHIP flag. 
If you specify the MEMF_FAST flag, your allocation will fail on any Amiga that has only CHIP memory. 
Use MEMF_ANY if you would prefer FAST memory. 

MEMF_PUBLIC 

This indicates that the memory should be accessible to other tasks. Although this flag doesn't do 
anything right now, using this flag will help ensure compatibility with possible future features of the 
OS (like virtual memory and memory protection). 

MEMF_CLEAR 

This indicates that the memory should be initialized with zeros. 

MEMF_LOCAL (V37) 

This indicates memory which is located on the motherboard which is not initialized on reset. 

MEMF_24BITDMA (V37) 

This indicates that the memory should be allocated within the 24 bit address space, so that the memory 
can be used in Zorro-ll expansion device DMA transactions. This bit is for use by Zorro-ll DMA devices 
only. It is not for general use by applications. 

MEMF_REVERSE (V37) 

Indicates that the memory list should be searched backwards for the highest address memory chunk 
which can be used for the memory allocation. 

If an application does not specify any attributes when allocating memory, the system tries to satisfy the request 
with the first memory available on the system memory lists, which is MEMF_FAST if available, followed by 
MEMF_CHIP. 

Make Sure You Have Memory. Always check the result of any memory allocation to be sure 
the type and amount of memory requested is available. Failure to do so will lead to trying to 
use an non-valid pointer. 
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Allocating System Memory 

The following examples show how to allocate memory. 

APTR apointer , anotherptr, yap; 
if (! (apointer = AllocMem (100 , MEMF_ANY) ) ) 
{ /* COULDN'T GET MEMORY, EXIT */ } 

AllocMem() returns the address of the first byte of a memory block that is at least 1 00 bytes in size or NULL if 
there is not that much free memory. Because the requirement field is specified as MEMF_ANY (zero), memory 
will be allocated from any one of the system-managed memory regions. 

if (! (anotherptr = (APTR) AllocMem (1000 , MEMF_CHIP | MEMF_CLEAR) ) ) 
{ /* COULDN'T GET MEMORY, EXIT */ } 

The example above allocates only chip-accessible memory, which the system fills with zeros before it lets the 
application use the memory. If the system free memory list does not contain enough contiguous memory bytes in 
an area matching your requirements, AllocMemQ returns a zero. You must check for this condition. 

If you are using Release 2, you can use the AllocVec() function to allocate memory. In addition to allocating a 
block of memory, this function keeps track of the size of the memory block, so your application doesn't have to 
remember it when it deallocates that memory block. The AllocVec() function allocates a little more memory to 
store the size of the memory allocation request. 

if ( ! (yap = (APTR)AllocVec (512, MEMFJCLEAR) ) ) 
{ /* COULDN'T GET MEMORY, EXIT */ } 



Freeing System Memory 

The following examples free the memory chunks shown in the previous calls to AllocMem(). 

FreeMem (apointer , 100); 
FreeMem (anotherptr , 1000); 

A memory block allocated with AllocVec() must be returned to the system pool with the FreeVec(). This function 
uses the stored size in the allocation to free the memory block, so there is no need to specify the size of the 
memory block to free. 

FreeVec (yap) ; 

FreeMemQ and FreeVecQ return no status. However, if you attempt to free a memory block in the middle of a 
chunk that the system believes is already free, you will cause a system crash. Applications must free the same 
size memory blocks that they allocated. An allocated block may not be deallocated as smaller pieces. Due to the 
internal way the system rounds up and aligns allocations. Partial deallocations can corrupt the system memory 
list. 

Leave Memory Allocations Out Of Interrupt Code. Do not allocate or deallocate system 
memory from within interrupt code. The "Exec Interrupts" chapter explains that an interrupt 
may occur at any time, even during a memory allocation process. As a result, system data 
structures may not be internally consistent at this time. 
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Memory Information Functions 

The memory information routines AvailMemQ and TypeOfMem() can provide the amount of memory available in 
the system, and the attributes of a particular block of memory. 

Memory Requirements 

The same attribute flags used in memory allocation routines are valid for the memory information routines. There 
is also an additional flag, MEMF_LARGEST, which can be used in the AvailMem() routine to find out what the 
largest available memory block of a particular type is. Specifying the MEMF_TOTAL flag will return the total 
amount of memory currently available. 

Calling Memory Information Functions 

The following example shows how to find out how much memory of a particular type is available. 

ULONG size; 

size = AvailMem(MEMF_CHIP|MEMF_LARGEST) ; 

AvailMem() returns the size of the largest chunk of available chip memory. 

AvailMemQ May Not Be Totally Accurate. Because of multitasking, the return value from 
AvailMem() may be inaccurate by the time you receive it. 

The following example shows how to determine the type of memory of a specified memory address. 

ULONG memtype ; 

memtype = TypeOf Mem ( (APTR) 0x090000) ; 

if ((memtype & MEMF_CHIP) == MEMF_CHIP) {/* ...It's chip memory... */} 

TypeOfMemQ returns the attributes of the memory at a specific address. If it is passed an invalid memory 
address, TypeOfMem() returns NULL. This routine is normally used to determine if a particular chunk of memory 
is in chip memory. 



Using Memory Copy Functions 

For memory block copies, the CopyMem() and CopyMemQuick() functions can be used. 
Copying System Memory 

The following samples show how to use the copying routines. 

APTR source, target; 

source = AllocMem(1000 , MEMF_CLEAR) ; 
target = AllocMem (1000 , MEMF_CHIP) ; 
CopyMem (source, target, 1000); 

458 Amiga ROM Kernel Reference Manual: Libraries 

CopyMem() copies the specified number of bytes from the source data region to the target data region. The 
pointers to the regions can be aligned on arbitrary address boundaries. CopyMemQ will attempt to copy the 
memory as efficiently as it can according to the alignment of the memory blocks, and the amount of data that it 
has to transfer. These functions are optimized for copying large blocks of memory which can result in 
unnecessary overhead if used to transfer very small blocks of memory. 

CopyMemQuick (source, target, 1000); 

CopyMemQuickQ performs an optimized copy of the specified number of bytes from the source data region to 
the target data region. The source and target pointers must be longword aligned and the size (in bytes) must be 
divisible by four. 

Not All Copies Are Supported. Neither CopyMem() nor CopyMemQuick() supports copying 
between regions that overlap. 

Summary of System Controlled Memory Handling Routines 

AllocMemO and FreeMem() 

These are system-wide memory allocation and deallocation routines. They use a memory free-list 
owned and managed by the system. 

AvailMemQ 

This routine returns the number of free bytes in a specified type of memory. 

TypeOfMem() 

This routine returns the memory attributes of a specified memory address. 

CopyMem()/CopyMemQuick() 

CopyMem() is a general purpose memory copy routine. CopyMemQuick() is an optimized version of 
CopyMemQuick(), but has restrictions on the size and alignment of the arguments. 

Allocating Multiple Memory Blocks 

Exec provides the routines AllocEntryQ and FreeEntryQ to allocate multiple memory blocks in a single call. 
AllocEntry() accepts a data structure called a MemList, which contains the information about the size of the 
memory blocks to be allocated and the requirements, if any, that you have regarding the allocation. The MemList 
structure is found in the include file <exec/memory.h> and is defined as follows: 

struct MemList 

{ 

struct Node ml_Node; 

UWORD ml_NumEntries; /* number of MemEntrys */ 

struct MemEntry ml_ME [1] ; /* where the MemEntrys begin*/ 



Node 

allows you to link together multiple MemLists. However, the node is ignored by the routines 
AllocEntry() and FreeEntry(). 

ml_NumEntries 

tells the system how many MemEntry sets are contained in this MemList. Notice that a Mem List is a 
variable-length structure and can contain as many sets of entries as you wish. 
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The MemEntry structure looks like this: 

struct MemEntry 

{ 

union { 

ULONG meu_Reqs; /* the AllocMem requirements */ 

APTR meu_Addr; /* address of your memory */ 

} me_Un ; 
ULONG me_Length; /* the size of this request */ 

}; 
Sample Code for Allocating Multiple Memory Blocks 

Here's an example of showing how to use the AllocEntry() with multiple blocks of memory. 

;/* allocentry.c - Execute me to compile me with SAS C 5.10 

LC -bl -cfistq -v -y - j 73 allocentry.c 

Blink FROM LIB : c . o, allocentry . o TO allocentry LIBRARY LIB : LC . lib, LIB : Amiga . lib 

quit ; 

allocentry.c - example of allocating several memory areas. 

*/ 

#include <exec/types . h> 
#include <exec/memory . h> 
#include <clib/exec_protos . h> 
#include <stdio.h> 
#include <stdlib.h> 

#ifdef LATTICE 

int CXBRK(void) { return(O); } /* Disable Lattice CTRL/C handling */ 

void chkabort (void) { return; } /* really */ 

#endif 

#define ALLOCERROR 0x80000000 

struct MemList *memlist; /* pointer to a MemList structure */ 

struct MemBlocks /* define a new structure because C cannot initialize unions */ 

{ 

struct MemList mn_head; /* one entry in the header */ 

struct MemEntry mn_body[3] ; /* additional entries follow directly as */ 

} memblocks; /* part of the same data structure */ 

VOID main (VOID) 

{ 

memblocks . mn_head.ml_NumEntries -4; /* 4! Since the MemEntry starts at 1 ! */ 

/* Describe the first piece of memory we want. Because of our MemBlocks structure */ 
/* setup, we reference the first MemEntry differently when initializing it. */ 
memblocks . mn_head . ml_ME [0] .me_Reqs = MEMF_CLEAR; 
memblocks . mn_head . ml_ME [0] . me_Length = 4 000; 

memblocks .mn_body [0] .me_Reqs = MEMF_CHIP | MEMF_CLEAR; /* Describe the other pieces of*/ 
memblocks .mn_body [0] .me_Length = 100000; /* memory we want. Additional */ 

memblocks. mn_body [1] .me_Reqs = MEMF_PUBLIC | MEMF_CLEAR ; / * MemEntries are initialized this */ 

memblocks .mn_body [1] .me_Length = 200000; /* way. If we wanted even more en- */ 

memblocks .mn_body [2] .me_Reqs = MEMF_PUBLIC; /* tries, we would need to declare */ 

memblocks .mn_body [2] .me_Length = 25000; /* a larger MemEntry array in our */ 

/* MemBlocks structure. */ 



memlist = (struct MemList *)AllocEntry ( (struct MemList *) &memblocks) ; 

if ( (ULONG) memlist & ALLOCERROR) /* 'error' bit 31 is set (see below). */ 

{ 

printf ( "AllocEntry FAILED\n") ; 
exit (200) ; 

} 

/* We got all memory we wanted. Use it and call FreeEntryO to free it */ 
printf ( "AllocEntry succeeded - now freeing all allocated blocks\n"); 
FreeEntry (memlist) ; 
} 
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AllocEntry() returns a pointer to a new MemList of the same size as the MemList that you passed to it. For 
example, ROM code can provide a MemList containing the requirements of a task and create a RAM-resident 
copy of the list containing the addresses of the allocated entries. The pointer to the MemList is used as the 
argument for FreeEntryO to free the memory blocks. 

Assembly Does Not Have MemEntry. The MemList structure used by assembly programmers 
is slightly different; it has only a label for the start of the MemEntry array. See the Exec 
AllocEntry() Autodoc for an example of using AllocEntryQ from assembler. 

Result of Allocating Multiple Memory Blocks 

The MemList created by AllocEntryQ contains MemEntry entries. MemEntrys are defined by a union 
statement, which allows one memory space to be defined in more than one way. 

If AllocEntry() returns a value with bit 31 clear, then all of the meu_Addr positions in the returned MemList will 
contain valid memory addresses meeting the requirements you have provided. To use this memory area, you 
would use code similar to the following: 

#define ALLOCERROR 0x80000000 
struct MemList *ml ; 
APTR data, moredata; 

if ( ! ((ULONG) ml & ALLOCERROR))) /* After calling AllocEntry to allocate ml */ 

{ 

data = ml - >ml_ME [ ] . me_Addr ; 
moredata = ml - >ml_ME [ 1 ] .me_Addr; 

} 

else exit (200) ; /* error during AllocEntry */ 

If AllocEntryO has problems while trying to allocate the memory you have requested, instead of the address of a 
new MemList, it will return the memory requirements value with which it had the problem. Bit 31 of the value 
returned will be set, and no memory will be allocated. Entries in the list that were already allocated will be freed. 
For example, a failed allocation of cleared Chip memory (MEMF_CLEAR | MEMF_CHIP) could be indicated with 
0x80010002, where bit 31 indicates failure, bit 16 is the MEMF_CLEAR flag and bit 1 is the MEMF_CHIP flag. 

Multiple Memory Blocks and Tasks 

If you want to take advantage of Exec's automatic cleanup, use the MemList and AllocEntryO facility to do your 
dynamic memory allocation. 

In the Task control block structure, there is a list header named tc_MemEntry. This is the list header that you 
initialize to include MemLists that your task has created by call(s) to AllocEntryO. Here is a short program 
segment that handles task memory list header initialization only. It assumes that you have already run 
AllocEntryO as shown in the simple AllocEntryO example above. 

struct Task *tc; 
struct MemList *ml ; 

/* First initialize the task pointer and AllocEntryO the memlist ml */ 

if ( ! tc->tc_MemEntry) 



NewList (tc->tc_MemEntry) ; /* Initialize the task's memory */ 

/* list header. Do this once only! */ 
AddTail (tc->tc_MemEntry, ml); 
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Assuming that you have only used the AllocEntryQ method (or AllocMem() and built your own custom 
MemList), the system now knows where to find the blocks of memory that your task has dynamically allocated. 
The RemTask() function automatically frees all memory found on tc_MemEntry. 

CreateTask() Sets Up A MemList. The amiga.lib CreateTaskQ function, and other system 
task and process creation functions use a MemList in tc_MemEntry so that the Task 
structure and stack will be automatically deallocated when the Task is removed. 

Summary of Multiple Memory Blocks Allocation Routines 

AllocEntry() and FreeEntry() 

These are routines for allocating and freeing multiple memory blocks with a single call. 

lnitStruct() 

This routine initializes memory from data and offset values in a table. Typically only assembly 
language programs benefit from using this routine. For more details see the Amiga ROM Kernel 
Reference Manual: Include & Autodocs. 



Other Memory Functions 



struct MemHeader { 






struct Node 


mh Node ; 




TJWORD 


mh Attributes; 


/ 


struct MemChunk 


*mh First; 


/ 


APTR 


mh Lower; 


/ 


APTR 


mh Upper; 


/ 


ULONG 


mh Free ; 


/ 



AllocateQ and Deallocate() use a memory region header, called MemHeader, as part of the calling sequence. 
You can build your own local header to manage memory locally. This structure takes the form: 



characteristics of region */ 

first free region */ 

lower memory bound */ 

upper memory bound +1 */ 

/* total number of free bytes */ 

}; 

mhAttrlbutes 

is ignored by Allocate() and Deallocate(). 

mh_First 

is the pointer to the first MemChunk structure. 

mh_Lower 

is the lowest address within the memory block. This must be a multiple of eight bytes. 

mh_Upper 

is the highest address within the memory block + 1 . The highest address will itself be a multiple of 
eight if the block was allocated to you by AllocMem(). 

mh_Free 

is the total free space. 

This structure is included in the include files <exec/memory.h> and <exec/memory.i>. 

The following sample code fragment shows the correct initialization of a MemHeader structure. It assumes that 
you wish to allocate a block of memory from the global pool and thereafter manage it yourself using Allocate() 
and Deallocate(). 
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;/* allocate. c - Execute me to compile me with SAS C 5.10 

LC -bl -cfistq -v -y - j 73 allocate. c 

Blink FROM LIB : c . o, allocate . o TO allocate LIBRARY LIB : LC . lib, LIB : Amiga . lib 

quit ; 

allocate. c - example of allocating and using a private memory pool. 

*/ 

#include <exec/types . h> 
#include <exec/memory . h> 
#include <clib/exec_protos . h> 
#include <stdio.h> 
#include <stdlib.h> 

#ifdef LATTICE 

int CXBRK(void) { return(O); } /* Disable Lattice CTRL/C handling */ 

void chkabort (void) { return; } /* really */ 

#endif 

#define BLOCKSIZE 4000 /* or whatever you need */ 

VOID main (VOID) 

{ 

struct MemHeader *mh; 
struct MemChunk *mc; 
APTR blockl, block2; 

/* Get the MemHeader needed to keep track of our new block. */ 

mh = (struct MemHeader *)AllocMem ( (LONG) sizeof (struct MemHeader), MEMF_CLEAR) ; 

if ( !mh) exit (10) ; 

/* Get the actual block the above MemHeader will manage. */ 
if ( ! (mc = (struct MemChunk *)AllocMem (BLOCKSIZE, 0)) ) ; 

{ 

FreeMem(mh, (LONG) sizeof (struct MemHeader)); 
exit (10) ; 

} 

mh- >mh_Node . ln_Type = NT_MEMORY ; 

mh->mh_First = mc; 

mh->mh_Lower = (APTR)mc; 

mh->mh_Upper = (APTR) (BLOCKSIZE + (ULONG)mc); 

mh->mh_Free = BLOCKSIZE; 

mc->mc_Next = NULL; /* Set up first chunk in the freelist */ 

mc->mc_Bytes = BLOCKSIZE; 

blockl = (APTR) Allocate (mh, 20) ; 
block2 = (APTR) Allocate (mh, 314); 

printf ("Our MemHeader struct at $%lx. Our block of memory at $%lx\n", mh, mc) ; 
printf ( "Allocated from our pool: blockl at $%lx, block2 at $%lx\n", blockl, block2); 

FreeMem(mh, (LONG) sizeof (struct MemHeader)); 
FreeMem(mc, (LONG) BLOCKSIZE) ; 
} 

How Memory Is Tagged. Only free memory is "tagged" using a MemChunk linked list. Once 
memory is allocated, the system has no way of determining which task now has control of that 
memory. 

If you allocate memory from the system, be sure to deallocate it when your task exits. You can accomplish this 
with matched deallocations, or by adding a MemList to your task's tc_MemEntry, or you can deallocate the 
memory in the finalPC routine (which can be specified if you perform AddTaskQ yourself). 

Allocating Memory at an Absolute Address 

For special advanced applications, AllocAbs() is provided. Using AllocAbsQ, an application can allocate a 
memory block starting at a specified absolute memory address. If the memory is already allocated or if there is 
not enough memory available for the request, AllocAbs() returns a zero. 
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Be aware that an absolute memory address which happens to be available on one Amiga may not be available on 
a machine with a different configuration or different operating system revision, or even on the same machine at a 
different times. For example, a piece of memory that is available during expansion board configuration might not 
be available at earlier or later times. Here is an example call to AllocAbs(): 

APTR absoluteptr; 

absoluteptr = (APTR) AllocAbs (10000 , 0x2F0000); 
if ( ! (absoluteptr) ) 

{ /* Couldn't get memory, act accordingly. */ } 

/* After we're done using it, we call FreeMem ( ) to free the memory */ 

/* block. */ 

FreeMem (absoluteptr, 10000); 

Adding Memory to the System Pool 

When non-Autoconfig memory needs to be added to the system free pool, the AddMemList() function can be 
used. This function takes the size of the memoryblock, its type, the priority for the memory list, the base address 
and the name of the memory block. A MemHeader structure will be placed at the start of the memory block, the 
remainder of the memory block will be made available for allocation. For example: 

AddMemList (0x200000, MEMF_FAST, 0, OxFOOOOO, "FZeroBoard"); 

will add a two megabyte memory block, starting at $F00000 to the system free pool as Fast memory. The 
memory list entry is identified with "FZeroBoard". 



Function Reference 



The following are brief descriptions of the Exec functions that handle memory management. See the Amiga ROM 
Kernel Reference Manual: Includes and Autodocs for details on each call. 

Table 20-1 : Exec Memory Functions 



Memory Function 



Description 



AllocMemO 

AddMemList() 

AllocAbs() 

Allocate() 

AllocEntry() 

AllocVec() 

AvailMem() 

CopyMem() 

CopyMemQuickO 

Deallocate() 

FreeEntry() 

FreeMem() 

FreeVec() 

lnitStruct() 

TypeOfMem() 



Allocate memory with specified attributes. If an application needs to allocate 

some memory, it will usually use this function. 

Add memory to the system free pool. 

Allocate memory at a specified location. 

Allocate memory from a private memory pool. 

Allocate multiple memory blocks. 

Allocate memory with specified attributes and keep track of the size (V36). 

Return the amount of free memory, given certain conditions. 

Copy memory block, which can be non-aligned and of arbitrary length. 

Copy aligned memory block. 

Return memory block allocated, with Allocate() to the private memory pool. 

Free multiple memory blocks, allocated with AllocEntry(). 

Free a memory block of specified size, allocated with AllocMem(). 

Free a memory block allocated with AllocVec(). 

Initialize memory from a table. 

Determine attributes of a specified memory address. 
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Chapter 21 
Exec Tasks 



One of the most powerful features of the Amiga operating system is its ability to run and manage multiple 
independent program tasks, providing each task with processor time based on their priority and activity. These 
tasks include system device drivers, background utilities, and user interface environments, as well as normal 
application programs. This multitasking capability is provided by the Exec library's management of task creation, 
termination, scheduling, event signals, traps, exceptions, and mutual exclusion. 

This chapter deals with Exec on a lower level than most applications programmers need and assumes you are 
already familiar with the Exec basics discussed in the "Introduction to Exec" chapter of this manual. 

Task Structure 



Exec maintains task context and state information in a task-control data structure. Like most Exec structures, 
Task structures are dynamically linked onto various task queues through the use of an embedded Exec list Node 
structure (see the "Exec Lists and Queues" chapter). Any task can find its own task structure by calling 
FindTask(NULL). The C-language form of this structure is defined in the <exec/tasks.h> include file: 



struct Task 
struct 
UBYTE 
UBYTE 
BYTE 
BYTE 
ULONG 
ULONG 
ULONG 
ULONG 
UWORD 
UWORD 
APTR 
APTR 
APTR 
APTR 
APTR 
APTR 
APTR 
VOID 
VOID 
struct 
APTR 



{ 



Node tc 
tc 
tc 
tc 
tc 
tc 
tc 
tc 
tc 
tc 
tc 
tc 
tc 
tc 
tc 
tc 
tc 
tc 
(*tc 
(*tc 

List tc 
tc 



_Node ; 

_Flags; 

_State; 

_IDNestCnt; 

_TDNestCnt; 

SigAlloc; 
_SigWait; 
_SigRecvd; 
_SigExcept ; 
_TrapAlloc; 

TrapAble; 

ExceptData; 

ExceptCode; 
_TrapData; 

TrapCode ; 

SPReg; 
_SPLower ; 
_SPUpper; 
_Switch) () ; 
JLaunch) ( ) ; 
_MemEntry; 

UserData; 



/* intr disabled nesting */ 

/* task disabled nesting */ 

/* sigs allocated */ 

/* sigs we are waiting for */ 

/* sigs we have received */ 

/* sigs we will take excepts for */ 

/* traps allocated */ 

/* traps enabled */ 

/* points to except data */ 

/* points to except code */ 

/* points to trap code */ 

/* points to trap data */ 

/* stack pointer */ 

/* stack lower bound */ 

/* stack upper bound + 2*/ 

/* task losing CPU */ 

/* task getting CPU */ 

/* allocated memory */ 

/* per task data */ 
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A similar assembly code structure is available in the <exec/tasks.i> include file. 

Most of these fields are not relevant for simple tasks; they are used by Exec for state and administrative 
purposes. A few fields, however, are provided for the advanced programs that support higher level environments 
(as in the case of processes) or require precise control (as in devices). The following sections explain these fields 
in more detail. 



Task Creation 



To create a new task you must allocate a task structure, initialize its various fields, and then link it into Exec with a 
call to AddTaskQ. The task structure may be allocated by calling the AllocMem() function with the 
MEMF CLEAR and MEMF PUBLIC allocation attributes. These attributes indicate that the data structure is to be 



pre-initialized to zero and that the structure is shared. 

The Task fields that require initialization depend on how you intend to use the task. For the simplest of tasks, 
only a few fields must be initialized: 

tc_Node 

The task list node structure. This includes the task's priority, its type, and its name (refer to the chapter 
"Exec Lists and Queues"). 

tc_SPLower 

The lower memory bound of the task's stack. 

tc_SPUpper 

The upper memory bound of the task's stack. 

tc_SPReg 

The initial stack pointer. Because task stacks grow downward in memory, this field is usually set to the 
same value as tc_SPUpper. 

Zeroing all other unused fields will cause Exec to supply the appropriate system default values. Allocating the 
structure with the MEMF_CLEAR attribute is an easy way to be sure that this happens. 

Once the structure has been initialized, it must be linked to Exec. This is done with a call to AddTask() in which 
the following parameters are specified: 

AddTask (struct Task *task, APTR initialPC, APTR finalPC ) 

The task argument is a pointer to your initialized Task structure. Set initialPC to the entry point of your task 
code. This is the address of the first instruction the new task will execute. 

Set finalPC to the address of the finalization code for your task. This is a code section that will receive control if 
the initialPC routine ever performs a return (rts). This exists to prevent your task from being launched into 
random memory upon an accidental return. The finalPC routine should usually perform various program-related 
clean-up duties and should then remove the task. If a zero is supplied for this parameter, Exec will use its default 
finalization code (which simply calls the RemTask() function). 

Under Release 2, AddTaskQ returns the address of the newly added task or NULL for failure. Under 1 .3 and 
older versions of the OS, no values are returned. 
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Task Creation With Amiga.lib 

A simpler method of creating a task is provided by the amiga.lib Exec support function CreateTask(), which can 
be accessed if your code is linked with amiga.lib. 

CreateTask (char *name, LONG priority, APTR initialPC, ULONG stacksize) 

A task created with CreateTaskQ may be removed with the amiga.lib DeleteTask() function, or it may simply 
return when it is finished. CreateTask() adds a MemList to the tc_MemEntry of the task it creates, describing all 
memory it has allocated for the task, including the task stack and the Task structure itself. This memory will be 
deallocated by Exec when the task is either explicitly removed (RemTask() or DeleteTask()) or when it exits to 
Exec's default task removal code (RemTask()). 

Note that a bug in the CreateTask() code caused a failed memory allocation to go unnoticed in V33 and early 
versions of Release 2 amiga.lib. 

If your development language is not linkable with amiga.lib, it may provide an equivalent built-in function, or you 
can create your own based on the createtask.c code in the Amiga ROM Kernel Reference Manual: Includes and 
Autodocs. 

Depending on the priority of a new task and the priorities of other tasks in the system, the newly added task may 
begin execution immediately. 



Sharing Library Pointers. Although in most cases it is possible for a parent task to pass a 
library base to a child task so the child can use that library, for some libraries, this is not 
possible. For this reason, the only library base sharable between tasks is Exec's library base. 

Here is an example of simple task creation. In this example there is no coordination or communication between 
the main process and the simple task it has created. A more complex example might use named ports and 
messages to coordinate the activities and shutdown of two tasks. Because our task is very simple and never calls 
any system functions which could cause it to be signalled or awakened, we can safely remove the task at any 
time. 

Keep This In Mind. Because the simple task's code is a function in our program, we must 
stop the subtask before exiting. 

;/* simpletask. c - Execute me to compile me with SAS C 5.10 

LC -bl -cfistq -v -y - j 73 simpletask. c 

Blink FROM LIB : c . o, simpletask . o TO simpletask LIBRARY LIB : LC . lib, LIB : Amiga . lib 

quit 

simpletask. c - Uses the amiga.lib function CreateTaskO to create a simple 
subtask. See the Includes and Autodocs manual for CreateTaskO source code 

*/ 

#include <exec/types .h> 
#include <exec/memory . h> 
#include <exec/tasks .h> 
#include <libraries/dos . h> 

#include <clib/exec_protos . h> 
#include <clib/alib_protos . h> 

#include <stdlib.h> 
#include <stdio.h> 

#ifdef LATTICE 

int CXBRK(void) { return(O); } /* Disable Lattice CTRL/C handling */ 

int chkabort (void) {return (0) ; } 

#endif 

#define STACK_SIZE 1000L 

/* Task name, pointers for allocated task struct and stack */ 

struct Task *task = NULL; 

char *simpletaskname = "SimpleTask" ; 

ULONG sharedvar; 

/* our function prototypes */ 

void simpletask (void) ; 

void cleanexit (UBYTE *,LONG); 

void main (int argc,char **argv) 

{ 

sharedvar = 0L; 

task = CreateTask (simpletaskname, , simpletask, STACK_SIZE) ; ; 
if (! task) cleanexit ( "Can' t create task" , RETURN_FAIL) ; 

printf("This program initialized a variable to zero, then started a\n"); 
printf ( "separate task which is incrementing that variable right now,\n"); 
printf ( "while this program waits for you to press RETURN. \n" ) ; 
printf ("Press RETURN now: " ) ; 
getchar ( ) ; 

printf ("The shared variable now equals %ld\n" , sharedvar) ; 

/* We can simply remove the task we added because our simpletask does not make */ 

/* any system calls which could cause it to be awakened or signalled later. */ 

Forbid ( ) ; 

DeleteTask (task) ; 

Permit () ; 

cleanexit ( " " , RETURN OK) ; 



void simpletask ( ) 

{ 

while (sharedvar < 0x8000000) sharedvar+t ; 

/* Wait forever because main ( ) is going to RemTaskO us */ 

Wait (0L) ; 
} 

void cleanexit (UBYTE *s, LONG e) 

{ 

if(*s) printf ( "%s\n" , s) ; 

exit (e) ,- 
} 

Task Stack 

Every task requires a stack. All task stacks are user mode stacks (in the language of the 68000) and are 
addressed through the A7 CPU register. All normal code execution occurs on this task stack. Special modes of 
execution (processor traps and system interrupts for example) execute on a single supervisor mode stack and do 
not directly affect task stacks. 

Task stacks are normally used to store local variables, subroutine return addresses, and saved register values. 
Additionally, when a task loses the processor, all of its current registers are preserved on this stack (with the 
exception of the stack pointer itself, which must be saved in the task structure). 

The amount of stack used by a task can vary widely. The theoretical minimum stack size is 72 bytes, which is the 
number required to save 17 CPU registers and a single return address. Of course, a stack of this size would not 
give you adequate space to perform any subroutine calls (because the return address occupies stack space). On 
the other hand, a stack size of 1 K would suffice to call most system functions but would not allow much in the way 
of local variable storage. Processes that call DOS library functions need an additional 1500 bytes of stack. 
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Because stack-bounds checking is not provided as a service of Exec, it is important to provide enough space for 
your task stack. Stack overflows are always difficult to debug and may result not only in the erratic failure of your 
task but also in the mysterious malfunction of other Amiga subsystems. Some compilers provide a 
stack-checking option. 

You Can't Always Check The Stack. Such stack-checking options generally cannot be used if 
part of your code will be running on the system stack (interrupts, 680x0 exceptions, handlers, 
servers), or on a different task's stack (libraries, devices, created tasks). 

When choosing your stack size, do not cut it too close. Remember that any recursive routines in your code may 
use varying amounts of stack, and that future versions of system routines may use additional stack variables. By 
dynamically allocating buffers and arrays, most application programs can be designed to function comfortably 
within the default process stack size of 4000 bytes. 

Task Priority 

A task's priority indicates its importance relative to other tasks. Higher-priority tasks receive the processor before 
lower-priority tasks do. Task priority is stored as a signed number ranging from -128 to +127. Higher priorities are 
represented by more positive values; zero is considered the neutral priority. Normally, system tasks execute 
somewhere in the range of +20 to -20, and most application tasks execute at priority 0. 

It is not wise to needlessly raise a task's priority. Sometimes it may be necessary to carefully select a priority so 
that the task can properly interact with various system tasks. The SetTaskPri() Exec function is provided for this 
purpose. 

Task Termination 

Task termination may occur as the result of a number of situations: 

A program returning from its initialPC routine and dropping into its finalPC routine or the system default 
finalizer. 



A task trap that is too serious for a recovery action. This includes traps like processor bus error, odd 
address access errors, etc. 

A trap that is not handled by the task. For example, the task might be terminated if your code happened 
to encounter a processor TRAP instruction and you did not provide a trap handling routine. 

An explicit call to Exec RemTask() or amiga.lib DeleteTask(). 

Task termination involves the deallocation of system resources and the removal of the task structure from Exec. 
The most important part of task termination is the deallocation of system resources. A task must return all 
memory that it allocated for its private use, it must terminate any outstanding I/O commands, and it must close 
access to any system libraries or devices that it has opened. 

It is wise to adopt a strategy for task clean-up responsibility. You should decide whether resource allocation and 
deallocation is the duty of the creator task or the newly created task. Often it is easier and safer for the creator to 
handle the resource allocation and deallocation on behalf of its offspring. In such cases, before removing the 
child task, you must make sure it is in a safe state such as Wait(OL) and not still using a resources or waiting for 
an event or signal that might still occur. 
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NOTE: Certain resources, such as signals and created ports, must be allocated and 
deallocated by the same task that will wait on them. Also note that if your subtask code is part 
of your loaded program, you must not allow your program to exit before its subtasks have 
cleaned up their allocations, and have been either deleted or placed in a safe state such as 
Wait(OL). 



Task Exclusion 



From time to time the advanced system program may find it necessary to access global system data structures. 
Because these structures are shared by the system and by other tasks that execute asynchronously to your task, 
a task must prevent other tasks from using these structures while it is reading from or writing to them. This can be 
accomplished by preventing the operating system from switching tasks by forbidding or disabling. A section of 
code that requires the use of either of these mechanisms to lock out access by others is termed a critical section. 
Use of these methods is discouraged. For arbitrating access to data between your tasks, semaphores are a 
superior solution. (See the "Exec Semaphores" chapter) 

Forbidding Task Switching 

Forbidding is used when a task is accessing shared structures that might also be accessed at the same time from 
another task. It effectively eliminates the possibility of simultaneous access by imposing nonpreemptive task 
scheduling. This has the net effect of disabling multitasking for as long as your task remains in its running state. 
While forbidden, your task will continue running until it performs a call to Wait() or exits from the forbidden state. 
Interrupts will occur normally, but no new tasks will be dispatched, regardless of their priorities. 

When a task running in the forbidden state calls the Wait() function, directly or indirectly, it implies a temporary 
exit from its forbidden state. Since almost all stdio, device I/O, and file I/O functions must WaitQ for I/O 
completion, performing such calls will cause your task to Wait(), temporarily breaking the forbid. While the task is 
waiting, the system will perform normally. When the task receives one of the signals it is waiting for, it will again 
reenter the forbidden state. To become forbidden, a task calls the Forbid() function. To escape, the Permit() 
function is used. The use of these functions may be nested with the expected affects; you will not exit the 
forbidden mode until you call the outermost Permit(). 

As an example, the Exec task list should only be accessed when in a ForbidQ state. Accessing the list without 
forbidding could lead to incorrect results or it could crash the entire system. To access the task list also requires 
the program to disable interrupts which is discussed in the next section. 

Disabling Tasks 

Disabling is similar to forbidding, but it also prevents interrupts from occurring during a critical section. Disabling 
is required when a task accesses structures that are shared by interrupt code. It eliminates the possibility of an 



interrupt accessing shared structures by preventing interrupts from occurring. Use of disabling is strongly 
discouraged. 

To disable interrupts you can call the Disable() function. To enable interrupts again, use the Enable() function. 
Although assembler DISABLE and ENABLE macros are provided, assembler programmers should use the 
system functions rather than the macros for upwards compatibility, ease of debugging, and smaller code size. 
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Like forbidden sections, disabled sections can be nested. To restore normal interrupt processing, an Enable() 
call must be made for every DisableQ. Also like forbidden sections, any direct or indirect call to the Wait() 
function will enable interrupts until the task regains the processor. 

WARNING: It is important to realize that there is a danger in using disabled sections. 
Because the software on the Amiga depends heavily on its interrupts occurring in nearly real 
time, you cannot disable for more than a very brief instant. Disabling interrupts for more than 
250 microseconds can interfere with the normal operation of vital system functions, especially 
serial I/O. 

WARNING: Masking interrupts by changing the 68000 processor interrupt priority levels with 
the move sr instruction can also be dangerous and is very strongly discouraged. The 
disable- and enable-related functions control interrupts through the 4703 custom chip and not 
through the 68000 priority level. In addition, the processor priority level can be altered only 
from supervisor mode (which means this process is much less efficient). 

It is never necessary to both DisableQ and ForbidQ. Because disabling prevents interrupts, it also prevents 
preemptive task scheduling. When disable is used within an interrupt, it will have the effect of locking out all 
higher level interrupts (lower level interrupts are automatically disabled by the CPU). Many Exec lists can only be 
accessed while disabled. Suppose you want to print the names of all system tasks. You would need to access 
both the TaskReady and TaskWait lists from within a single disabled section. In addition, you must avoid calling 
system functions that would break a disable by an indirect call to Wait() (printf() for example). In this example, 
the names are gathered into a list while task switching is disabled. Then task switching is enabled and the names 
are printed. 

;/* tasklist.c - Execute me to compile me with SAS C 5.10 

LC -bl -cfistq -v -y -J73 tasklist.c 

Blink FROM LIB : c . o, tasklist . o TO tasklist LIBRARY LIB : LC . lib, LIB : Amiga . lib 

quit 

tasklist.c - Snapshots and prints the ExecBase task list 

*/ 

#include <exec/types .h> 
#include <exec/lists . h> 
#include <exec/nodes . h> 
#include <exec/memory . h> 
#include <exec/execbase . h> 

#include <clib/alib_protos . h> 
#include <clib/exec_protos . h> 

#include <stdio.h> 
#include <string.h> 

#ifdef LATTICE 

int CXBRK(void) { return(O); } /* disable SAS/C CTRL-C handing */ 

int chkabort (void) (return(O); } 

#endif 

static UBYTE *VersTag = "$VER: tasklist 37.2 (31.3.92)"; 
extern struct ExecBase *SysBase; 

/* Use extended structure to hold task information */ 
struct TaskNode { 

struct Node tn_Node; 

ULONG tn_TaskAddress; 

ULONG tn_SigAlloc; 

ULONG tn_SigWait; 

UBYTE tn Name [3 2] ; 



void main(int argc, char **argv) 

{ 

struct List *ourtasklist ; 

struct List *exectasklist ; 

struct Task *task; 

struct TaskNode *node, *tnode, *rnode = NULL; 

struct Node * execnode; 

/* Allocate memory for our list */ 

if (ourtasklist = AllocMem (sizeof (struct List), MEMF_CLEAR) ) { 

/* Initialize list structure (ala NewListO) */ 

ourtasklist->lh_Head = (struct Node *) &ourtasklist->lh_Tail ; 

ourtasklist ->lh_Tail = 0; 

ourtasklist->lh_TailPred = (struct Node *) &ourtasklist->lh_Head; 

/* Make sure tasks won't switch lists or go away */ 
Disable () ; 

/* Snapshot task WAIT list */ 
exectasklist = & (SysBase->TaskWait) ; 
for (execnode = exectasklist->lh_Head; 

execnode->ln Succ; execnode = execnode ->ln Succ) 



{ 



if (tnode = AllocMem (sizeof (struct TaskNode), MEMF_CLEAR) ) 

{ 

/* Save task information we want to print */ 

strncpy ( tnode ->tn_Name, execnode ->ln_Name, 32); 

tnode - >tn_Node . ln_Pri = execnode - >ln_Pri ; 

tnode->tn_TaskAddress = (ULONG) execnode; 

tnode->tn_SigAlloc = ((struct Task *) execnode) ->tc_SigAlloc; 

tnode->tn_SigWait = ((struct Task*) execnode) ->tc_SigWait ; 

AddTail (ourtasklist , (struct Node *)tnode); 

} 

else break; 



/* Snapshot task READY list */ 
exectasklist = & (SysBase->TaskReady) ; 
for (execnode = exectasklist->lh_Head; 

execnode ->ln Succ; execnode = execnode ->ln Succ) 



{ 



if (tnode = AllocMem (sizeof (struct TaskNode), MEMF_CLEAR) ) 

{ 

/* Save task information we want to print */ 
strncpy ( tnode ->tn_Name, execnode ->ln_Name, 32); 
tnode - >tn_Node . ln_Pri = execnode - >ln_Pr i ; 
tnode->tn_TaskAddress = (ULONG) execnode; 

tnode->tn_SigAlloc = ((struct Task *) execnode) ->tc_SigAlloc; 
tnode->tn_SigWait = ((struct Task*) execnode) ->tc_SigWait ; 
AddTail (ourtasklist , (struct Node *)tnode); 
if(!rnode) mode = tnode; /* first READY task */ 

} 
else 

break; 



} 



/* Re-enable interrupts and taskswitching */ 
Enable ( ) ; 

/* Print now (printing above would have defeated a Forbid or Disable) */ 
printf("Pri Address SigAlloc SigWait Taskname\n" ) ; 

node = (struct TaskNode *) (ourtasklist->lh_Head) ; 

printf ("\nWAITING:\n") ; 

while (tnode = (struct TaskNode *) node->tn_Node . ln_Succ) 

{ 

if (tnode == mode) 

printf ( "\nREADY: \n" ) ; /* we set mode above */ 
printf ("%02d 0x%081x 0x%081x 0x%081x %s\n" , 

node->tn_Node . ln_Pri, node->tn_TaskAddress , node->tn_SigAlloc, 



node->tn_SigWait , node->tn_Name) ; 

/* Free the memory, no need to remove the node, referenced once only */ 
FreeMem (node, sizeof (struct TaskNode) ) ; 
node = tnode ; 

} 

FreeMem (ourtasklist, sizeof (struct List)); 

/* Say who we are */ 

printf ("\nTHIS TASK:\n"); 

task = FindTask(NULL) ; 

printf ("%02d 0x%081x 0x%081x 0x%081x %s\n" , 

task->tc_Node . ln_Pri , task, task->tc_SigAlloc, 

task->tc_SigWait , task->tc_Node . ln_Name) ; 



Task Semaphores 

Semaphores can be used for the purposes of mutual exclusion. With this method of locking, all tasks agree on a 
locking convention before accessing shared data structures. Tasks that do not require access are not affected 
and will run normally, so this type of exclusion is considered preferable to forbidding and disabling. This form of 
exclusion is explained in more detail in the "Exec Semaphores" chapter. 



Task Exceptions 



Exec can provide a task with its own task-local "interrupt" called an exception. When some exceptional event 
occurs, an Exec exception occurs which stops a particular task from executing its normal code and forces it to 
execute a special, task-specific exception handling routine. 

If you are familiar with the 680x0, you may be used to using the term "exceptions" in a different way. The 680x0 
has its own form of exception that has nothing to do with an Exec exception. These are discussed in more detail 
in the "Task Traps" section of this chapter. Do not confuse Exec exceptions with 680x0 exceptions. 

To set up an exception routine for a task requires setting values in the task's control structure (the Task 
structure). The tc_ExceptCode field should point to the task's exception handling routine. If this field is zero, 
Exec will ignore all exceptions. The tc_ExceptData field should point to any data the exception routine needs. 

Exec exceptions work using signals. When a specific signal or signals occur, Exec will stop a task and execute its 
exception routine. Use the Exec function SetExceptQ to tell Exec which of the task's signals should trigger the 
exception. 

When an exception occurs, Exec stops executing the tasks normal code and jumps immediately into the 
exception routine, no matter what the task was doing. The exception routine operates in the same context the 
task's normal code; it operates in the CPU's user mode and uses the task's stack. 

Before entering the exception routine, Exec pushes the normal task code's context onto the stack. This includes 
the PC, SR, D0-D7, and A0-A6 registers. Exec then puts certain parameters in the processor registers for the 
exception routine to use. DO contains a signal mask indicating which signal bit or bits caused the exception. Exec 
disables these signals when the task enters its exception routine. If more than one signal bit is set (i.e. if two 
signals occurred simultaneously), it is up to the exception routine to decide in what order to process the two 
different signals. A1 points to the related exception data (from tc_ExceptData), and A6 contains the Exec library 
base. You can think of an exception as a subtask outside of your normal task. Because task exception code 
executes in user mode, however, the task stack must be large enough to supply the extra space consumed during 
an exception. 
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While processing a given exception, Exec prevents that exception from occurring recursively. At exit from your 
exception-processing code, you should make sure DO contains the signal mask the exception routine received in 
DO because Exec looks here to see which signals it should reactivate. When the task executes the RTS 
instruction at the end of the exception routine, the system restores the previous contents of all of the task registers 
and resumes the task at the point where it was interrupted by the exception signal. 



Exceptions Are Tricky. Exceptions are difficult to use safely. An exception can interrupt a task 
that is executing a critical section of code within a system function, or one that has locked a 
system resource such as the disk or blitter (note that even simple text output uses the blitter.) 
This possibility makes it dangerous to use most system functions within an exception unless 
you are sure that your interrupted task was performing only local, non-critical operations. 



Task Traps 



Task traps are synchronous exceptions to the normal flow of program control. They are always generated as a 
direct result of an operation performed by your program's code. Whether they are accidental or purposely 
generated, they will result in your program being forced into a special condition in which it must immediately 
handle the trap. Address error, privilege violation, zero divide, and trap instructions all result in task traps. They 
may be generated directly by the 68000 processor (Motorola calls them "exceptions") or simulated by software. 

A task that incurs a trap has no choice but to respond immediately. The task must have a module of code to 
handle the trap. Your task may be aborted if a trap occurs and no means of handling it has been provided. 
Default trap handling code (tc_TrapCode) is provided by the OS. You may instead choose to do your own 
processing of traps. The tc_TrapCode field is the address of the handler that you have designed to process the 
trap. The tc_TrapData field is the address of the data area for use by the trap handler. 

The system's default trap handling code generally displays a Software Error Requester or Alert containing an 
exception number and the program counter or task address. Processor exceptions generally have numbers in the 
range hex 00 to 2F. The 68000 processor exceptions of particular interest are as follows. 





Table 21-1 


Traps (68000 Exception Vector Numbers) 


2 


Bus error 


access of nonexistent memory 


3 


Address error 


long/word access of odd address (68000) 


4 


Illegal instruction 


illegal opcode (other than Axxx or Fxxx) 


5 


Zero divide 


processor division by zero 


6 


CHK instruction 


register bounds error trap by CHK 


7 


TRAPV instruction 


overflow error trap by TRAPV 


8 


Privilege violation 


user execution of supervisor opcode 


9 


Trace 


status register TRACE bit trap 


10 


Line 1010 emulator 


execution of opcode beginning with $A 


11 


Line 1111 emulator 


execution of opcode beginning with $F 


32-47 


Trap instructions 


TRAP N instruction where N = to 15 



A system alert for a processor exception may set the high bit of the longword exception number to indicate an 
unrecoverable error (for example $80000005 for an unrecoverable processor exception #5). System alerts with 
more complex numbers are generally Amiga-specific software failures. These are built from the definitions in the 
<exec/alerts.h> include file. 
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The actual stack frames generated for these traps are processor-dependent. The 68010, 68020, and 68030 
processors will generate a different type of stack frame than the 68000. If you plan on having your program 
handle its own traps, you should not make assumptions about the format of the supervisor stack frame. Check 
the flags in the AttnFlags field of the ExecBase structure for the type of processor in use and process the stack 
frame accordingly. 

Trap Handlers 



For compatibility with the 68000, Exec performs trap handling in supervisor mode. This means that all task 
switching is disabled during trap handling. At entry to the task's trap handler, the system stack contains a 
processor-dependent trap frame as defined in the 68000/10/20/30 manuals. A longword exception number is 
added to this frame. That is, when a handler gains control, the top of stack contains the exception number and 
the trap frame immediately follows. 

To return from trap processing, remove the exception number from the stack (note that this is the supervisor 
stack, not the user stack) and then perform a return from exception (rte). 



Because trap processing takes place in supervisor mode, with task dispatching disabled, it is strongly urged that 
you keep trap processing as short as possible or switch back to user mode from within your trap handler. If a trap 
handler already exists when you add your own trap handler, it is smart to propagate any traps that you do not 
handle down to the previous handler. This can be done by saving the previous address from tc_TrapCode and 
having your handler pass control to that address if the trap which occurred is not one you wish to handle. 

The following example installs a simple trap handler which intercepts processor divide-by-zero traps, and passes 
on all other traps to the previous default trap code. The example has two code modules which are linked 
together. The trap handler code is in assembler. The C module installs the handler, demonstrates its 
effectiveness, then restores the previous tc_TrapCode. 

;/* trap_c.c - Execute me to compile me with SAS C 5.10 

LC -bO -cfistq -v -y - j 73 trap_c.c 

Blink FROM LIB : c . o, trap_c . o, trap_a . o TO trap LIBRARY LIB : LC . lib, LIB : Amiga . lib 

quit 

trap_c.c - C module of sample integer divide-by-zero trap 

*/ 

#include <exec/types .h> 
#include <exec/tasks . h> 
#include <clib/exec_protos . h> 
#include <stdlib.h> 
#include <stdio.h> 

#ifdef LATTICE 

int CXBRK(void) { return(O); } /* Disable Lattice CTRL/C handling */ 

int chkabort (void) {return(O); } 

#endif 

extern ULONG trapaO ; /* assembler trap code in trapa.asm */ 

APTR oldTrapCode; 
ULONG countdivO; 

void main (int argc, char **argv) 

{ 

struct Task *thistask; 
ULONG k , j ; 

thistask = FindTask (NULL) ; 

/* Save our task's current trap code pointer */ 
oldTrapCode = thistask- >tc_TrapCode; 

/* Point task to our assembler trap handler code. Ours will just count */ 
/* divide-by-zero traps, and pass other traps on to the normal TrapCode */ 
thistask- >tc_TrapCode = (APTR) trapa; 

countdivO = 0L; 

for(k=0; k<4 ; k++) /* Let's divide by zero a few times */ 

{ 

printf ( "dividing %ld by zero... ",k); 

j = k/OL; 

printf ("did it\n"); 

} 
printf ( "\nDivide by zero happened %ld times\n" , countdivO) ; 

thistask- >tc_TrapCode = oldTrapCode; /* Restore old trap code */ 
} 

* trap_a.asm - Example trap handling code (leaves DO intact) . Entered 

* in supervisor mode with the following on the supervisor stack: 

* (sp) .1 = trap# 

* 4(sp) Processor dependent exception frame 

INCLUDE "exec/types . i" 
INCLUDE "libraries/dos.i" 

XDEF trapa 
XREF countdivO 



trapa: 



XREF _oldTrapCode 

CODE 

CMPI.L #5, (SP) 
BNE.S notdivO 



endtrap: 



notdivO : 



ADDQ 
RTE 

TST.L 
BEQ.S 
MOVE . L 
RTS 



#1 ,_countdivO 
#4,SP 



_oldTrapCode 
endtrap 
_oldTrapCode, - (SP) 



our trap handler entry 

is this a divide by zero ? 

no 

yes, increment our divO count 

; remove exception number from SSP 
; return from exception 

is there another trap handler ? 
no, so we'll exit 
yes , go on to old TrapCode 
jumps to old TrapCode 



Trap Instructions 

The TRAP instructions in the 68000 generate traps 32-47. Because many independent pieces of system code 
may desire to use these traps, the AllocTrap() and FreeTrap() functions are provided. These work in a fashion 
similar to that used by AllocSignal() and FreeSignal(), mentioned in the "Exec Signals" chapter. 

Allocating a trap is simply a bookkeeping job within a task. It does not affect how the system calls the trap 
handler; it helps coordinate who owns what traps. Exec does nothing to determine whether or not a task is 
prepared to handle a particular trap. It simply calls your code. It is up to your program to handle the trap. 

To allocate any trap, you can use the following code: 

if (-1 == (trap = AllocTrap(-l) ) ) 

printf("all trap instructions are in use\n"); 

Or you can select a specific trap using this code: 

if (-1 == (trap = AllocTrap (3) ) ) 

printf("trap #3 is in use\n"); 

To free a trap, you use the FreeTrap() function passing it the trap number to be freed. 
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Processor and Cache Control 

Exec provides a number of to control the processor mode and, if available, the caches. All these functions work 
independently of the specific M68000 family processor type. This enables you to write code which correctly 
controls the state of both the MC68000 and the MC68040. Along with processor mode and cache control, 
functions are provided to obtain information about the condition code register (CCR) and status register (SR). No 
functions are provided to control a paged memory management unit (PMMU) or floating point unit (FPU). 

Table 21-2: Processor and Cache Control Functions 



Function 


Description 


GetCC() 


Get processor condition codes. 


SetSR() 


Get/set processor status register. 


SuperState() 


Set supervisor mode with user stack. 


Supervisor() 


Execute a short supervisor mode function. 


UserState() 


Return to user mode with user stack. 


CacheClearE() 


Flush CPU instruction and/or data caches (V37). 


CacheClearU() 


Flush CPU instruction and data caches (V37). 


CacheControl() 


Global cache control (V37). 


CachePostDMA() 


Perform actions prior to hardware DMA (V37). 


CachePreDMAQ 


Perform actions after hardware DMA (V37). 



Supervisor Mode 

While in supervisor mode, you have complete access to all data and registers, including those used for task 
scheduling and exceptions, and can execute privileged instructions. In application programs, normally only task 
trap code is directly executed in supervisor mode, to be compatible with the MC68000. For normal applications, it 
should never be necessary to switch to supervisor mode itself, only indirectly through Exec function calls. 
Remember that task switching is disabled while in supervisor mode. If it is absolutely needed to execute code in 
supervisor mode, keep it as brief as possible. 

Supervisor mode can only be entered when a 680x0 exception occurs (an interrupt or trap). The Supervisor^) 
function allows you to trap an exception to a specified assembly function. In this function your have full access to 
all registers. No registers are saved when your function is invoked. You are responsible for restoring the system 
to a sane state when you are done. You must return to user mode with an rte instruction. You must not return to 
user mode by executing a privileged instruction which clears the supervisor bit in the status register. Refer to a 
manual on the M68000 family of CPUs for information about supervisor mode and available privileged instructions 
per processor type. 

The MC68000 has two stacks, the user stack (USP) and supervisor stack (SSP). As of the MC68020 there are 
two supervisor stacks, the interrupt stack pointer (ISP) and the master stack pointer (MSP). The SuperState() 
function allows you to enter supervisor mode with the USP used as SSP. The function returns the SSP, which will 
be the MSP, if an MC68020 or greater is used. Returning to user mode is done with the UserState() function. 
This function takes the SSP as argument, which must be saved when SuperStateQ is called. Because of 
possible problems with stack size, Supervisor^) is to be preferred over SuperState(). 
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Status Register 

The processor status register bits can be set or read with the SetSR() function. This function operates in 
supervisor mode, thus both the upper and lower byte of the SR can be read or set. Be very sure you know what 
you are doing when you use this function to set bits in the SR and above all never try to use this function to enter 
supervisor mode. Refer to the M68000 Programmers Reference Manual by Motorola Inc. for information about the 
definition of individual SR bits per processor type. 

Condition Code Register 

On the MC68000 a copy of the processor condition codes can be obtained with the MOVE SR,<ea> instruction. 
On MC68010 processors and up however, the instruction move ccr, <ea> must be used. Using the specific 
MC68000 instruction on later processors will cause a 680x0 exception since it is a privileged instruction on those 
processors. The GetCCQ function provides a processor independent way of obtaining a copy of the condition 
codes. For all processors there are 5 bits which can indicate the result of an integer or a system control 
instruction: 

X - extend N - negative Z - zero V - overflow C - carry 

The X bit is used for multiprecision calculations. If used, it is copy of the carry bit. The other bits state the result of 
a processor operation. 

Cache Functions 

As of the MC68020 all processors have an instruction cache, 256 bytes on the MC68020 and MC68030 and 4 
KBytes on a MC68040. The MC68030 and MC68040 have data caches as well, 256 bytes and 4 KBytes 
respectively. All the processors load instructions ahead of the program counter (PC), albeit it that the MC68000 
and MC68010 only prefetch one and two words respectively. This means the CPU loads instructions ahead of the 
current program counter. For this reason self-modifying code is strongly discouraged. If your code modifies or 
decrypts itself just ahead of the program counter, the pre-fetched instructions may not match the modified 
instructions. If self-modifying code must be used, flushing the cache is the safest way to prevent this. 

DMA Cache Functions 

The CachePreDMA() and CachePostDMA() functions allow you to flush the data cache before and after Direct 
Memory Access. Typically only DMA device drivers benefit from this. These functions take the processor type, 
possible MMU and cache mode into account. When no cache is available they end up doing nothing. These 



functions can be replaced with ones suitable for different cache hardware. Refer to the ROM Kernel Reference 
Manual: Includes and Autodocs for implementation specifics. 

Since DMA device drivers read and write directly to memory, they are effected by the CopyBack feature of the 
MC68040 (explained below). Using DMA with CopyBack mode requires a cache flush. If a DMA device needs to 
read RAM via DMA, it must make sure that the data in the caches has been written to memory first, by calling 
CachePreDMAQ. In case of a write to memory, the DMA device should first clear the caches with 
CachePreDMA(), write the data and flush the caches again with CachePostDMAQ. 
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The 68040 and CPU Caches 

The 68040 is a much more powerful CPU than its predecessors. It has 4K of cache memory for instructions and 
another 4K cache for data. The reason for these two separate caches is so that the CPU core can access data 
and CPU instructions at the same time. 

Although the 68040 provides greater performance it also brings with it greater compatibility problems. Just the 
fact that the caches are so much larger than Motorola's 68030 CPU can cause problems. However, this is not its 
biggest obstacle. 

The 68040 data cache has a mode that can make the system run much faster in most cases. It is called 
CopyBack mode. When a program writes data to memory in this mode, the data goes into the cache but not into 
the physical RAM. That means that if a program or a piece of hardware were to read that RAM without going 
through the data cache on the 68040, it will read old data. CopyBack mode effects two areas of the Amiga: DMA 
devices and the CPU's instruction reading. 

CopyBack mode effects DMA devices because they read and write data directly to memory. Using DMA with 
CopyBack mode requires a cache flush. If a DMA device needs to read RAM via DMA, it must first make sure that 
data in the caches has been written to memory. It can do this by calling the Exec function CachePreDMA(). If a 
DMA device is about to write to memory, it should call CachePreDMA() before the write, do the DMA write, and 
then call CachePostDMA(), which makes sure that the CPU uses the data just written to memory. 

An added advantage of using the CachePreDMAQ and CachePostDMA() functions is that they give the OS the 
chance to tell the DMA device that the physical addresses and memory sizes are not the same. This will make it 
possible in the future to add features such as virtual memory. See the Autodocs for more information on these 
calls. 

The other major compatibility problem with the 68040's CopyBack mode is with fetching CPU instructions. CPU 
instructions have to be loaded into memory so the CPU can copy them into its instruction cache. Normally, 
instructions that will be executed are written to memory by the CPU (i.e., loading a program from disk). In 
CopyBack mode, anything the CPU writes to memory, including CPU instructions, doesn't actually go into 
memory, it goes into the data cache. If instructions are not flushed out of the data cache to RAM, the 68040 will 
not be able to find them when it tries to copy them into the instruction cache for execution. It will instead find and 
attempt to execute whatever garbage data happened to be left at that location in RAM. 

To remedy this, any program that writes instructions to memory must flush the data cache after writing. The V37 
Exec function CacheClearUQ takes care of this. Release 2 of the Amiga OS correctly flushes the caches as 
needed after it does the LoadSegQ of a program (LoadSegQ loads Amiga executable programs into memory 
from disk). Applications need to do the same if they write code to memory. It can do that by calling 
CacheClearUQ before the call to CreateProc(). In C that would be: 

extern struct ExecBase *SysBase; 

/* If we are in 2.0, call CacheClearU ( ) before CreateProc ( ) */ 
if (SysBase->LibNode . lib_Version >= 37) CacheClearU () ; 

/* Now do the CreateProc () call... */ 

proc=CreateProc ( . . . /* whatever your call is like */...); ... 
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For those of you programming in assembly language: 



*********************************************************************** 

* Check to see if we are running in V37 ROM or better. If so, we want 

* to call CacheClearU ( ) to make sure we are safe on future hardware 

* such as the 68040. This section of code assumes that a6 points at 

* ExecBase . aO/al/dO/dl are trashed in CacheClearU ( ) 



cmpi.w #37,LIB_VERSION(a6) 

bcs.s TooOld 

jsr _LVOCacheClearU(a6) 



TooOld: 



Check if exec is >= V37 

If less than V37, too old. . . 

Clear the cache . . . 

Exit gracefully. 



*********************************************************************** 

Note that CreateProc() is not the only routine where CopyBack mode could be a problem. Any program code 
copied into memory for execution that is not done via LoadSegQ will need to call CacheClearU(). Many input 
device handlers have been known to allocate and copy the handler code into memory and then exit back to the 
system. These programs also need to have this call in them. The above code will work under older versions of 
the OS, and will do the correct operations in Release 2 (and beyond). 



Function Reference 



The following chart gives a brief description of the Exec functions that control tasks. See the Amiga ROM Kernel 
Reference Manual: Includes and Autodocs for details about each call. 

Table 21-3: Exec Task, Processor and Cache Control Functions 



Exec Task Function 


Description 


AddTask() 


Add a task to the system. 


AllocTrap() 


Allocate a processor trap vector. 


Disable() 


Disable interrupt processing. 


Enable() 


Enable interrupt processing. 


FindTask() 


Find a specific task. 


Forbid() 


Forbid task rescheduling. 


FreeTrap() 


Release a process trap. 


Permit() 


Permit task rescheduling. 


SetTaskPri() 


Set the priority of a task. 


RemTask() 


Remove a task from the system. 


(Jache(Jleart() 


Flush CPU instruction and/or data caches (V3/). 


CacheClearUO 


Flush CPU instruction and data caches (V37). 


CacheControl() 


Global cache control (V37). 


CachePostDMA() 


Perform actions prior to hardware DMA (V37). 


CachePreDMA() 


Perform actions after hardware DMA (V37). 


GetCC() 


Get processor condition codes. 


SetSRO 


Get/set processor status register. 


SuperState() 


Set supervisor mode with user stack. 


Supervisor() 


Execute a short supervisor mode function. 


UserState() 


Return to user mode with user stack. 


Create I asky 


Amiga.hb function to setup and add a new task. 


DeleteTaskQ 


Amiga.lib function to delete a task created with CreateTaskQ. 



Chapter 22 
Exec Signals 



Tasks often need to coordinate with other concurrent system activities (like other tasks and interrupts). This 
coordination is handled by Exec through the synchronized exchange of specific event indicators called signals. 

This is the primary mechanism responsible for all intertask communication and synchronization on the Amiga. 
This signal mechanism operates at a low level and is designed for high performance. Signals are used 
extensively by the Exec message system as a way to indicate the arrival of an inter-task message. The message 
system is described in more detail in the "Exec Messages and Ports" chapter. 

Not for Beginners. This chapter concentrates on details about signals that most applications 
do not need to understand for general Amiga programming. For a general overview of signals, 
see the "Introduction to Exec" chapter of this manual. 



The Signal System 



The signal system is designed to support independent simultaneous events, so several signals can occur at the 
same time. Each task has 32 independent signals, 1 6 of which are pre-allocated for use by the operating system. 
The signals in use by a particular task are represented as bits in a 32-bit field in its Task structure 
(<exec/tasks.h>). Two other 32-bit fields in the Task structure indicate which signals the task is waiting for, and 
which signals have been received. 

Signals are task relative. A task can only allocate its own signals, and may only wait on its own signals. In 
addition, a task may assign its own significance to a particular signal. Signals are not broadcast to all tasks; they 
are directed only to individual tasks. A signal has meaning to the task that defined it and to those tasks that have 
been informed of its meaning. 

For example, signal bit 12 may indicate a timeout event to one task, but to another task it may indicate a message 
arrival event. You can never wait on a signal that you did not directly or indirectly allocate yourself, and any other 
task that wishes to signal you must use a signal that you allocated. 
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Signal Allocation 

As mentioned above, a task assigns its own meaning to a particular signal. Because certain system libraries may 
occasionally require the use of a signal, there is a convention for signal allocation. It is unwise ever to make 
assumptions about which signals are actually in use. 

Before a signal can be used, it must be allocated with the AllocSignalQ function. When a signal is no longer 
needed, it should be freed for reuse with FreeSignal(). 

BYTE AllocSignal ( LONG signalNum ) ; 
VOID FreeSignal ( LONG signalNum ) ; 

AllocSignal() marks a signal as being in use and prevents the accidental use of the same signal for more than 
one event. You may ask for either a specific signal number, or more commonly, you would pass -1 to request the 
next available signal. The state of the newly allocated signal is cleared (ready for use). Generally it is best to let 
the system assign you the next free signal. Of the 32 available signals, the lower 1 6 are reserved for system use. 
This leaves the upper 16 signals free for application programs to allocate. Other subsystems that you may call 
depend on AllocSignal(). 

The following C example asks for the next free signal to be allocated for its use: 

if (-1 == (signal = AllocSignal (-1) ) ) 

printf("no signal bits available\n" ) ; 
else 



printf ( "allocated signal number %ld\n", signal); 
/* Other code could go here */ 
FreeSignal (signal) 
} 

The value returned by AllocSignal() is a signal bit number. This value cannot be used directly in calls to 
signal-related functions without first being converted to a mask: 

mask = 1L << signal; 

It is important to realize that signal bit allocation is relevant only to the running task. You cannot allocate a signal 
from another task. Note that functions which create a signal MsgPort will allocate a signal from the task that calls 
the function. Such functions include OpenWindowQ, CreatePort(), and CreateMsgPort(). For this reason, only 
the creating task may Wait() (directly or indirectly) on the MsgPort's signal. Functions which call WaitQ include 
DolO(), WaitlO() and WaitPort(). 

Waiting for a Signal 

Signals are most often used to wake up a task upon the occurrence of some external event. Applications call the 
Exec Wait() function, directly or indirectly, in order to enter a wait state until some external event triggers a signal 
which awakens the task. 

Though signals are usually not used to interrupt an executing task, they can be used this way. Task exceptions, 
described in the "Exec Tasks" chapter, allow signals to act as a task-local interrupt. 
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The Wait() function specifies the set of signals that will wake up the task and then puts the task to sleep (into the 
waiting state). 

ULONG Wait ( ULONG signalSet ) ; 

Any one signal or any combination of signals from this set are sufficient to awaken the task. Wait() returns a 
mask indicating which signals satisfied the Wait() call. Note that when signals are used in conjunction with a 
message port, a set signal bit does not necessarily mean that there is a message at the message port. See the 
"Exec Messages and Ports" chapter for details about proper handling of messages. 

Because tasks (and interrupts) normally execute asynchronously, it is often possible to receive a particular signal 
before a task actually Wait()s for it. In such cases the Wait() will be immediately satisfied, and the task will not be 
put to sleep. 

The Wait() function implicitly clears those signal bits that satisfied the wait condition. This effectively resets those 
signals for reuse. However, keep in mind that a task might get more signals while it is still processing the previous 
signal. If the same signal is received multiple times and the signal bit is not cleared between them, some signals 
will go unnoticed. 

Be aware that using Wait() will break a Forbid() or Disable() state. Wait() cannot be used in supervisor mode or 
within interrupts. 

A task may Wait() for a combination of signal bits and will wake up when any of the signals occur. Wait() returns 
a signal mask specifying which signal or signals were received. Usually the program must check the returned 
mask for each signal it was waiting on and take the appropriate action for each that occurred. The order in which 
these bits are checked is often important. 

Here is a hypothetical example of a process that is using the console and timer devices, and is waiting for a 
message from either device and a possible break character issued by the user: 

consoleSignal = 1L << ConsolePort->mp_SigBit ; 

timerSignal = 1L << TimerPort->mp_SigBit ; 

userSignal = SIGBREAKF_CTRL_C; /* Defined in <dos/dos.h> */ 

signals = Wait (consoleSignal | timerSignal | userSignal); 



if (signals & consoleSignal) 

printf ( "new character\n" ) ; 

if (signals & timeOutSignal) 
printf ( "timeout\n" ) ; 

if (signals & userSignal) 

printf ("User Ctrl-C Abort\n"); 

This code will put the task to sleep waiting for a new character, or the expiration of a time period, or a Ctrl-C break 
character issued by the user. Notice that this code checks for an incoming character signal before checking for a 
timeout. Although a program can check for the occurrence of a particular event by checking whether its signal 
has occurred, this may lead to busy wait polling. Such polling is wasteful of the processor and is usually harmful 
to the proper function of the Amiga system. However, if a program needs to do constant processing and also 
check signals (a compiler for example) SetSignal(0,0) can be used to get a copy of your task's current signals. 

ULONG SetSignalf ULONG newSignals, ULONG signalSet ); 

Exec Signals 483 

SetSignal() can also be used to set or clear the state of the signals. Implementing this can be dangerous and 
should generally not be done. The following fragment illustrates a possible use of SetSignal(). 

signals = SetSignal (0 , 0) ; /* Get current state of signals */ 

if (signals & SIGBREAKF_CTRL_C) /* Check for Ctrl-C. */ 

{ 

printf ( "Break\n" ) ; /* Ctrl-C signal has been set. */ 

SetSignal (0, SIGBREAKF_CTRL_C) /* Clear Ctrl-C signal. */ 

} 

Generating a Signal 

Signals may be generated from both tasks and system interrupts with the Signal() function. 

VOID Signal ( struct Task *task, ULONG signalSet ) ; 

For example Signal(tc,mask) would signal the task with the specified mask signals. More than one signal can be 
specified in the mask. The following example code illustrates Wait() and Signal(). 

;/* signals. c - Execute me to compile me with SAS C 5.10 

LC -bl -cfistq -v -y - j 73 signals. c 

Blink FROM LIB : c . o, signals . o TO signals LIBRARY LIB : LC . lib, LIB : Amiga . lib 

quit 

*/ 

#include <exec/types . h> 
#include <exec/memory . h> 
#include <dos/dos.h> 

#include <clib/exec_protos . h> 
#include <clib/dos_protos . h> 
#include <clib/alib_protos . h> 
#include "stdio.h" 

#ifdef LATTICE 

int CXBRK(void) { return(O); } /* Disable Lattice CTRL/C handling */ 

int chkabort (void) { return(O); } /* really */ 

#endif 

static UBYTE *VersTag = "$VER: signals 37.1 (28.3.91)"; 

void subtaskcode (void) ; /* prototype for our subtask routine */ 

LONG mainsignum = -1; 

ULONG mains ig, wakeupsigs; 

struct Task *maintask = NULL, *subtask = NULL; 



UBYTE subtaskname [] = "RKM_signal_subtask" ; 

void main(int argc, char **argv) 

{ 

BOOL Done = FALSE, WaitingForSubtask = TRUE; 

/* We must allocate any special signals we want to receive. */ 
mainsignum = AllocSignal ( -1) ; 
if (mainsignum == -1) 

printf("No signals available\n" ) ; 
else 

{ 

mainsig = 1L << mainsignum; /* subtask can access this global */ 

maintask = FindTask (NULL) ; /* subtask can access this global */ 

printf("We alloc a signal, create a task, wait for signals\n" ) ; 
subtask = CreateTask (subtaskname, OL, subtaskcode, 2000); 
if ( ! subtask) 

printf ( "Can' t create subtask\n"); 
else 

{ 

printf ( "After subtask signals, press CTRL-C or CTRL-D to exit\n"); 

while ( ( !Done) | | (WaitingForSubtask) ) 

{ 

/* Wait on the combined mask for all of the signals we are 

* interested in. All processes have the CTRL_C thru CTRL_F 

* signals. We're also Waiting on the mainsig we allocated 

* for our subtask to signal us with. We could also Wait on 

* the signals of any ports/windows our main task created ... */ 

wakeupsigs = Wait (mainsig | SIGBREAKF_CTRL_C | SIGBREAKF_CTRL_D) ; 

/* Deal with all signals that woke us up - may be more than one */ 
if (wakeupsigs & mainsig) 

{ 

printf ( "Signalled by subtask\n"); 

WaitingForSubtask = FALSE; /* OK to kill subtask now */ 

} 
if (wakeupsigs & SIGBREAKF_CTRL_C) 

{ 

printf ("Got CTRL-C signal\n"); 

Done = TRUE ; 

} 
if (wakeupsigs & SIGBREAKF_CTRL_D) 

{ 

printf ("Got CTRL-D signal\n"); 

Done = TRUE ; 

} 
} 
Forbid ( ) ; 

DeleteTask (subtask) ; 
Permit ( ) ; 



} 



FreeSignal (mainsignum) ; 
} 



void subtaskcode (void) 

{ 

Signal (maintask, mainsig) ; 

Wait(OL) ; /* safe state in which this subtask can be deleted */ 

} 



Function Reference 



The following chart gives a brief description of the Exec functions that control task signalling. See the Amiga 
ROM Kernel Reference Manual: Includes and Autodocs for details about each call. 



Table 22-1 : Exec Signal Functions 



Exec Signal Function 



AllocSignalQ 

FreeSignal() 

SetSignal() 

Signal() 

Wait() 



Description 



Allocate a signal bit. 

Free a signal bit allocated with AllocSignal(). 

Query or set the state of the signals for the current task. 

Signal a task by setting signal bits in its Task structure. 

Wait for one or more signals from other tasks or interrupts. 
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Chapter 23 

Exec Lists and Queues 

The Amiga system software operates in a dynamic environment of data structures. An early design goal of Exec 
was to keep the system flexible and open-ended by eliminating artificial boundaries on the number of system 
structures used. Rather than using static system tables, Exec uses dynamically created structures that are added 
and removed as needed. These structures can be put in an unordered list, or in an ordered list known as a queue. 
A list can be empty, but never full. This concept is central to the design of Exec. Understanding lists and queues 
is important to understanding not only Exec itself, but also the mechanism behind the Amiga's message and port 
based interprocess communication. 

Exec uses lists to maintain its internal database of system structures. Tasks, interrupts, libraries, devices, 
messages, I/O requests, and all other Exec data structures are supported and serviced through the consistent 
application of Exec's list mechanism. Lists have a common data structure, and a common set of functions is used 
for manipulating them. Because all of these structures are treated in a similar manner, only a small number of list 
handling functions need be supported by Exec. 

List Structure 

A list is composed of a header and a doubly-linked chain of elements called nodes. The header contains memory 
pointers to the first and last nodes of the linked chain. The address of the header is used as the handle to the 
entire list. To manipulate a list, you must provide the address of its header. 



_\| 
/ / | First Node 

/ /I 



Head Node 



Tail Node 



/ / I /|\ 
/ / II 

/ / M/_l 

/_/ I 

\ | Second Node 

/_ I 



\ \ I /|\ 

\ \ II 

\ \ M/_l 

\ \ I I 

\ \ | Third Node 

\_\| I 

/ 

Figure 23-1 : Simplified Overview of an Exec List 
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Nodes may be scattered anywhere in memory. Each node contains two pointers; a successor and a predecessor. 
As illustrated above, a list header contains two placeholder nodes that contain no data. In an empty list, the head 
and tail nodes point to each other. 

Node Structure Definition 

A Node structure is divided into three parts: linkage, information, and content. The linkage part contains memory 
pointers to the node's successor and predecessor nodes. The information part contains the node type, the 
priority, and a name pointer. The content part stores the actual data structure of interest. For nodes that require 
linkage only, a small MinNode structure is used. 

struct MinNode 

{ 

struct MinNode *mln Succ; 



struct MinNode *mln_Pred; 

}; 

InSucc 

points to the next node in the list (successor). 

ln_Pred 

points to the previous node in the list (predecessor). 

When a type, priority, or name is required, a full-featured Node structure is used. 

struct Node 

{ 

struct Node *ln_Succ; 
struct Node *ln_Pred; 
UBYTE ln_Type ; 
BYTE ln_Pri; 

char * 1 n_Name ; 

}; 
ln_Type 

In Pri 



defines the type of the node (see <exec/nodes.h> for a list), 
specifies the priority of the node (+127 (highest) to -128 (lowest)). 



ln_Name 

points to a printable name for the node (a NULL-terminated string). 

The Node and MinNode structures are often incorporated into larger structures, so groups of the larger structures 
can easily be linked together. For example, the Exec Interrupt structure is defined as follows: 

struct Interrupt 

{ 

struct Node is_Node; 

APTR is_Data; 

VOID (*is_Code) () ; 

} ; 

Here the is_Data and is_Code fields represent the useful content of the node. Because the Interrupt structure 
begins with a Node structure, it may be passed to any of the Exec List manipulation functions. 
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Node Initialization 

Before linking a node into a list, certain fields may need initialization. Initialization consists of setting the ln_Type, 
ln_Pri, and ln_Name fields to their appropriate values (A MinNode structure does not have these fields). The 
successor and predecessor fields do not require initialization. 

The ln_Type field contains the data type of the node. This indicates to Exec (and other subsystems) the type, 
and hence the structure, of the content portion of the node (the extra data after the Node structure). The standard 
system types are defined in the <exec/nodes.h> include file. Some examples of standard system types are 
NT_TASK, NTJNTERRUPT, NT_DEVICE, and NT_MSGPORT. 

The ln_Pri field uses a signed numerical value ranging from +127 to -128 to indicate the priority of the node. 
Higher-priority nodes have greater values; for example, 1 27 is the highest priority, zero is nominal priority, and 
-128 is the lowest priority. Some Exec lists are kept sorted by priority order. In such lists, the highest-priority 
node is at the head of the list, and the lowest-priority node is at the tail of the list. Most Exec node types do not 
use a priority. In such cases, initialize the priority field to zero. 

The ln_Name field is a pointer to a NULL-terminated string of characters. Node names are used to find and 
identify list-bound objects (like public message ports and libraries), and to bind symbolic names to actual nodes. 
Names are also useful for debugging purposes, so it is a good idea to provide every node with a name. Take 



care to provide a valid name pointer; Exec does not copy name strings. 

This fragment initializes a Node called mylnt, an instance of the Interrupt data structure introduced above. 

struct Interrupt interrupt; 

interrupt . is_Node . ln_Type = NT_INTERRUPT ; 

interrupt . is_Node . ln_Pri = -10; 

interrupt . is_Node . ln_Name = "sample . interrupt" ; 

List Header Structure Definitions 

As mentioned earlier, a list header maintains memory pointers to the first and last nodes of the linked chain of 
nodes. It also serves as a handle for referencing the entire list. The minimum list header ("mlh_") and the 
full-featured list header ("lh_") are generally interchangeable. 

The structure MinList defines a minimum list header. 

struct MinList 

{ 

struct MinNode *mlh_Head; 
struct MinNode *mlh_Tail; 
struct MinNode *mlh_TailPred; 

}; 

mlhJHead 

points to the first node in the list. 

mlh Tail 

is always NULL. 

mlh_TailPred 

points to the last node in the list. 

Exec Lists and Queues 489 
In a few limited cases a full-featured List structure will be required: 

struct List 

{ 

struct Node *lh_Head; 
struct Node *lh_Tail; 
struct Node *lh_TailPred; 
UBYTE lh_Type ; 
UBYTE lh Pad; 



IhType 
lh_pad 



defines the type of nodes within the list (see <exec/nodes.h>). 



is a structure alignment byte. 

One subtlety here must be explained further. The list header is constructed in an efficient, but confusing manner. 
Think of the header as a structure containing the head and tail nodes for the list. The head and tail nodes are 
placeholders, and never carry data. The head and tail portions of the header actually overlap in memory. 
lh_Head and Ih Tail form the head node; lh_Tail and Ih TailPred form the tail node. This makes it easy to find 
the start or end of the list, and eliminates any special cases for insertion or removal. 



In Succ 




\ 
/ 


lh_Head 


| In Pred=0 


In Succ=0 


lh_Tail=0 | 




In Pred 


lh TailPred| 



The lh_Head and lh_Tail fields of the list header act like the ln_Succ and IhPred fields of a node. The lh_Tail 
field is set permanently to NULL, indicating that the head node is indeed the first on the list -- that is, it has no 
predecessors. See the figure above. 

Likewise, the lh_Tail and IhTailPred fields of the list header act like the ln_Succ and lh_Pred fields of a node. 
Here the NULL IhTail indicates that the tail node is indeed the last on the list -- that is, it has no successors. 
See the figure above. 

Header Initialization 

List headers must be properly initialized before use. It is not adequate to initialize the entire header to zero. The 
head and tail entries must have specific values. The header must be initialized as follows: 

1 . Set the IhJHead field to the address of IhTail. 

2. Clear the lh_Tail field. 

3. Set the lh_TailPred field to the address of IhJHead. 

4. Set lh_Type to the same data type as the nodes to be kept the list. (Unless you are using a MinList). 
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/* C example - equivalent to NewListO 
struct List list; 

list.lh_Head = (struct Node *; 

list.lh_Tail = 0; 

list . lh_TailPred = (struct Node*) 

/* Now set lh_Type, if needed */ 













lh Head 


/ 




\ 




\ 










/ 


lh_Tail=0 








lh TailPred 


— 


*/ 




I 
I 
I 




&lis 


3t.lh_Tail; 




&list 


: . lh Head; 





;Assembly example - equivalent to NEWLIST 

MOVE.L A0,LH_HEAD(A0) ;A0 points to the list header 

ADDQ.L #4,LH_HEAD(A0) ;Bump LH_HEAD(A0) to address of LH_TAIL 

CLR.L LH_TAIL(A0) 

MOVE . L A0 , LH_TAILPRED ( A0 ) 
;Now set LH TYPE, if needed. 



Figure 23-3: Initializing a List Header Structure 

The sequence of assembly instructions in the figure above is equivalent to the macro NEWLIST, contained in the 
include file <exec/lists.i>. Since the MinList structure is the same as the List structure except for the type and 
pad fields, this sequence of assembly language code will work for both structures. The sequence performs its 
function without destroying the pointer to the list header in A0 (which is why ADDQ.L is used). This function may 
also be accessed from C as a call to NewList(header), where header is the address of a list header. 



List Functions 



Exec provides a number of symmetric functions for handling lists. There are functions for inserting and removing 
nodes, for adding and removing head and tail nodes, for inserting nodes in a priority order, and for searching for 
nodes by name. The prototypes for Exec list handling functions are as follows. 

Exec Functions 

VOID AddHead ( struct List *list, struct Node *node 

VOID AddTail ( struct List *list, struct Node *node 

VOID Enqueue ( struct List *list, struct Node *node 

struct Node *FindName ( struct List *list, UBYTE *name ); 

VOID Insert ( struct List *list, struct Node *node, struct Node *pred ) ; 

VOID Remove ( struct Node *node ) ; 

struct Node *RemHead( struct List *list ) ; 

struct Node *RemTail ( struct List *list ); 

Exec Support Functions in amiga.lib 

VOID NewList( struct List *list ); 

In this discussion of the Exec list handling functions, header represents a pointer to List header, and node 
represents pointer to a Node. 
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Insertion and Removal 

The lnsert() function is used for inserting a new node into any position in a list. It always inserts the node 
following a specified node that is already part of the list. For example, lnsert(header,node,pred) inserts the node 
node after the node pred in the specified list. If the pred node points to the list header or is NULL, the new node 
will be inserted at the head of the list. Similarly, if the pred node points to the lh_Tail of the list, the new node will 
be inserted at the tail of the list. However, both of these actions can be better accomplished with the functions 
mentioned in the "Special Case Insertion" section below. 

The Remove() function is used to remove a specified node from a list. For example, Remove(node) will remove 
the specified node from whatever list it is in. To be removed, a node must actually be in a list. If you attempt to 
remove a node that is not in a list, you will cause serious system problems. 

Special Case Insertion 

Although the lnsert() function allows new nodes to be inserted at the head and the tail of a list, the AddHead() 
and AddTail() functions will do so with higher efficiency. Adding to the head or tail of a list is common practice in 
first-in-first-out (FIFO) or last-in-first-out (LIFO or stack) operations. For example, AddHead(header,node) would 
insert the node at the head of the specified list. 

Special Case Removal 

The two functions RemHeadQ and RemTail() are used in combination with AddHeadQ and AddTail() to create 
special list ordering. When you combine AddTail() and RemHeadQ, you produce a first-in-first-out (FIFO) list. 
When you combine AddHeadQ and RemHeadQ a last-in-first-out (LIFO or stack) list is produced. RemTail() 
exists for symmetry. Other combinations of these functions can also be used productively. 

Both RemHeadQ and RemTailQ remove a node from the list, and return a pointer to the removed node. If the list 
is empty, the function return a NULL result. 

MinList/MinNode Operations 

All of the above functions and macros will work with long or short format node structures. A MinNode structure 
contains only linkage information. A full Node structure contains linkage information, as well as type, priority and 
name fields. The smaller MinNode is used where space and memory alignment issues are important. The larger 
Node is used for queues or lists that require a name tag for each node. 



Prioritized Insertion 

The list functions discussed so far do not make use of the priority field in a Node. The Enqueue() function is 
equivalent to lnsert(), except it inserts nodes into a list sorting them according to their priority. It keeps the 
higher-priority nodes towards the head of the list. All nodes passed to this function must have their priority and 
name assigned prior to the call. Enqueue(header,mynode) inserts mynode behind the lowest priority node with a 
priority greater than or equal to mynode's. For Enqueue() to work properly, the list must already be sort 
according to priority. Because the highest priority node is at the head of the list, the RemHead() function will 
remove the highest-priority node. Likewise, RemTail() will remove the lowest-priority node. 
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FIFO Is Used For The Same Priority. If you add a node that has the same priority as another 
node in the queue, Enqueue() will use FIFO ordering. The new node is inserted following the 
last node of equal priority. 

Searching By Name 

Because many lists contain nodes with symbolic names attached (via the ln_Name field), it is possible to find a 
node by its name. This naming technique is used throughout Exec for such nodes as tasks, libraries, devices, 
and resources. 

The FindName() function searches a list for the first node with a given name. For example, FindName(header, 
"Furrbol") returns a pointer to the first node named "Furrbol." If no such node exists, a NULL is returned. The case 
of the name characters is significant; "foo" is different from "Foo." 
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Figure 23-4: Complete Sample List Showing all Interconnections 

More on the use of Named Lists 

To find multiple occurrences of nodes with identical names, the FindName() function is called multiple times. For 
example, if you want to find all the nodes with the name pointed to by name: 

VOID DisplayName (struct List *list,UBYTE *name) 

{ 

struct Node *node; 



if (node = FindName (list , name) 
while (node) 
{ 



printf ( "Found %s at location %lx\n" , node->ln_Name, node) ; 
node = FindName ( (struct List *) node , name ) ; 

} 
else printf ("No node with name %s f ound. \n" , name) ; 
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Notice that the second search uses the node found by the first search. The FindName() function never compares 
the specified name with that of the starting node. It always begins the search with the successor of the starting 
point. 

List Macros for Assembly Language Programmers 

Assembly language programmers may want to optimize their code by using assembly code list macros. Because 
these macros actually embed the specified list operation into the code, they result in slightly faster operations. 
The file <exec/lists.k> contains the recommended set of macros. For example, the following instructions implement 
the REMOVE macro: 



MOVE . L LN_SUCC (Al ) , AO 

MOVE . L LN_PRED (Al ) , Al 

MOVE.L A0,LN_SUCC(A1) 

MOVE.L A1,LN PRED(AO) 



get successor 

get predecessor 

fix up predecessor's succ pointer 

fix up successor's pred pointer 



Empty Lists 



It is often important to determine if a list is empty. This can be done in many ways, but only two are worth 
mentioning. If either the lh_TailPred field is pointing to the list header or the ln_Succ field of the lh_Head is 
NULL, then the list is empty. 

In C, for example, these methods would be written as follows: 

/* You can use this method. . . */ 
if (list->lh_TailPred == (struct Node *)list) 
printf ("list is empty\n"); 

/* Or you can use this method */ 

if (NULL == list->lh_Head->ln_Succ) 

printf ("list is empty\n"); 

In assembly code, if AO points to the list header, these methods would be written as follows: 

; Use this method. . . 
CMP . L LH_TAILPRED (AO ) , AO 
BEQ list_is_empty 

; Or use this method 
MOVE . L LH_HEAD (AO ) , Al 
TST.L LN_SUCC(A1) 
BEQ list_is_empty 

Because LHJHEAD and LN_SUCC are both zero offsets, the second case may be simplified or optimized by your 
assembler. 

Scanning a List 

Occasionally a program may need to scan a list to locate a particular node, find a node that has a field with a 
particular value, or just print the list. Because lists are linked in both the forward and backward directions, the list 
can be scanned from either the head or tail. 
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Here is a code fragment that uses a for loop to print the names of all nodes in a list: 



struct List *list; 
struct Node *node; 

for (node = list->lh_Head ; node->ln_Succ ; node = node->ln_Succ) 
printf("%lx -> %s\n" , node, node->ln_Name) ; 

A common mistake is to process the head or tail nodes. Valid data nodes have non-NULL successor and 
predecessor pointers. The above loop exits when node->ln_Succ is NULL. Another common mistake is to free 
a node from within a loop, then reference the free memory to obtain the next node pointer. An extra temporary 
pointer solves this second problem. 

In assembly code, it is more efficient to use a look-ahead cache pointer when scanning a list. In this example the 
list is scanned until the first zero-priority node is reached: 

MOVE.L (A1),D1 ; first node 

scan: MOVE.L D1,A1 

MOVE.L (A1),D1 ; lookahead to next 

BEQ.S not found ; end of list... 



TST.B LN_PRI(A1) 
BNE.S scan 



; found one 



not_f ound : 

Exec List Example 

The code below demonstrates the concepts and functions discussed in this chapter by building an 
application-defined Exec List. 

;/* buildlist.c - Execute me to compile me with SAS C 5.10 

LC -bl -cfistq -v -y -j73 buildlist.c 

Blink FROM LIB : c . o, buildlist . o TO buildlist LIBRARY LIB : LC . lib, LIB : Amiga . lib 

quit 

** The code below demonstrates the concepts and functions discussed in this 
** chapter by building an application-defined Exec List. 

** buildlist.c - example which uses an application-specific Exec list 
*/ 

#include <exec/types . h> 
#include <exec/lists . h> 
#include <exec/nodes . h> 
#include <exec/memory . h> 

#include <clib/alib_protos . h> 
#include <clib/exec_protos . h> 

#include <string.h> 
#include <stdio.h> 

#ifdef LATTICE 

int CXBRK(void) { return(O); } /* Disable Lattice CTRL/C handling */ 

void chkabort (void) { return; } /* really */ 

#endif 

/* Our function prototypes */ 

VOID AddName (struct List *, UBYTE *); 

VOID FreeNameNodes (struct List *); 

VOID DisplayNameList (struct List *); 

VOID DisplayName (struct List *, UBYTE *); 

struct NameNode { 

struct Node nn_Node; /* System Node structure */ 
UBYTE nn_Data [62] ; /* Node-specific data */ 

}; 

#define NAMENODE_ID 100 /* The type of "NameNode" */ 



VOID main (VOID) 

{ 

struct List *NameList; /* Note that a MinList would also work */ 

if (!( NameList = AllocMem (sizeof (struct List) ,MEMF_CLEAR) ) ) 

printf("Out of memory\n"); 
else { 

NewList (NameList) ; /* Important: prepare header for use */ 



AddName (NameList , "Name7 " ) 
AddName (NameList , "Name5 " ) 
AddName (NameList , "Name2 " ) 



AddName (NameList , "Name6 " ) 
AddName (NameList , "Name4 " ) 
AddName (NameList , "NameO " ) 



AddName (NameList , "Name7 " ) ; AddName (NameList , "Name5 " ) ; 
AddName (NameList , "Name3 " ) ; AddName (NameList , "Namel " ) ; 

DisplayName (NameList , "Name5") ; 
DisplayNameList (NameList) ; 

FreeNameNodes (NameList) ; 

FreeMem (NameList , sizeof (struct List)); /* Free list header */ 



} 



} 



/* Allocate a NameNode structure, copy the given name into the structure, 

* then add it the specified list. This example does not provide an 

* error return for the out of memory condition. 

*/ 

VOID AddName (struct List *list, UBYTE *name) 

{ 

struct NameNode *namenode; 

if (!( namenode = AllocMem (sizeof (struct NameNode) ,MEMF_CLEAR) )) 

printf("Out of memory\n"); 
else { 

strcpy ( namenode ->nn_Dat a, name) ; 

namenode - >nn_Node . ln_Name = namenode - >nn_Data ; 

namenode - >nn_Node . ln_Type = NAMENODE_ID ; 

namenode - >nn_Node . ln_Pr i = ; 

AddHead ( (struct List *)list, (struct Node *) namenode ) ; 
} 
} 

/* 

* Free the entire list, including the header. The header is not updated 

* as the list is freed. This function demonstrates how to avoid 

* referencing freed memory when deallocating nodes. 

*/ 

VOID FreeNameNodes (struct List *list) 

{ 

struct NameNode *worknode; 
struct NameNode *nextnode; 

worknode = (struct NameNode *) (list->lh_Head) ; /* First node */ 
while (nextnode = (struct NameNode *) ( worknode ->nn_Node . ln_Succ) ) { 

FreeMem (worknode, sizeof (struct NameNode) ) ; 

worknode = nextnode ; 
} 

} 

/* 

* Print the names of each node in a list. 

*/ 

VOID DisplayNameList (struct List *list) 

{ 

struct Node *node; 

if (list->lh_TailPred == (struct Node *)list) 

printf("List is empty. \n"); 
else { 

for (node = list->lh Head ; node->ln Succ ; node = node->ln Succ) 



printf ( "%lx -> %s\n" , node, node- >ln_Name) ; 



/* 

* Print the location of all nodes with a specified name. 

*/ 

VOID DisplayName (struct List *list, UBYTE *name) 

{ 

struct Node *node; 

if (node = FindName (list , name) ) { 
while (node) { 

printf ( "Found a %s at location %lx\n" , node- >ln_Name, node) ; 
node = FindName ( (struct List *) node , name ) ; 

} 
} else printf ("No node with name %s f ound. \n" ,name) ; 

} 

Important Note About Shared Lists 

It is possible to run into contention problems with other tasks when manipulating a list that is shared by more than 
one task. None of the standard Exec list functions arbitrates for access to the list. For example, if some other 
task happens to be modifying a list while your task scans it, an inconsistent view of the list may be formed. This 
can result in a corrupted system. 

Generally it is not permissible to read or write a shared list without first locking out access from other tasks. All 
users of a list must use the same arbitration method. Several arbitration techniques are used on the Amiga. 
Some lists are protected by a semaphore. The ObtainSemaphore() call grants ownership of the list (see the 
"Exec Semaphores" chapter for more information). Some lists require special arbitration. For example, you must 
use the Intuition LocklBase(O) call before accessing any Intuition lists. Other lists may be accessed only during 
Forbid() or Disable() (see the "Exec Tasks" chapter for more information). 

The preferred method for arbitrating use of a shared list is through semaphores because a semaphores only holds 
off other tasks that are trying to access the shared list. Rather than suspending all multitasking. Failure to lock a 
shared list before use will result in unreliable operation. 

Note that I/O functions including printf() generally call WaitQ to wait for I/O completion, and this allows other 
tasks to run. Therefore, it is not safe to print or Wait() while traversing a list unless the list is fully controlled by 
your application, or if the list is otherwise guaranteed not to change during multitasking. 
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Function Reference 



The following charts give a brief description of the Exec list and queue functions and assembler macros. See the 
Amiga ROM Kernel Reference Manual: Includes and Autodocs for details about each call. 

Table 23-1 : Exec List and Queue Functions 



Exec Function 


Description 


AddHead() 


Insert a node at the head of a list. 


AddTail() 


Append a node to the tail of a list. 


Enqueue() 


Insert or append a node to a system queue. 


FindName() 


Find a node with a given name in a system list. 


lnsert() 


Insert a node into a list. 


IsListEmpty 


Test if list is empty 


NewListQ 


Initialize a list structure for use. 


RemHead() 


Remove the head node from a list. 


Remove() 


Remove a node from a list. 


RemTailQ 


Remove the tail node from a list. 



Table 23-2: Exec List and Queue Assembler Macros 



Exec Function 


Description 


NEWLIST 


Initialize a list header for use. 


TSTLIST 


Test if list is empty (list address in register). No arbitration needed. 


TSTLST2 


Test is list is empty (from effective address of list). Arbitration needed. 


SUCC 


Get next node in a list. 


PRED 


Get previous node in a list. 


IFEMPTY 


Branch if list is empty. 


IFNOTEMPTY 


Branch if list is not empty. 


TSTNODE 


Get next node, test if at end of list. 


NEXTNODE 


Get next node, go to exit label if at end. 


ADDHEAD 


Add node to head of list. 


ADDTAIL 


Add node to tail of list. 


REMOVE 


Remove node from a list. 


REMHEAD 


Remove node from head of list. 


REMHEADQ 


Remove node from head of list quickly. 


REMTAIL 


Remove node from tail of list. 
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Chapter 24 

Exec Messages and Ports 

For interprocess communication, Exec provides a consistent, high-performance mechanism of messages and 
ports. This mechanism is used to pass message structures of arbitrary sizes from task to task, interrupt to task, or 
task to software interrupt. In addition, messages are often used to coordinate operations between cooperating 
tasks. This chapter describes many of the details of using messages and ports that the casual Amiga 
programmer won't need. See the "Introduction to Exec" chapter of this manual for a general introduction to using 
messages and ports. 

A message data structure has two parts: system linkage and message body. The system linkage is used by Exec 
to attach a given message to its destination. The message body contains the actual data of interest. The 
message body is any arbitrary data up to 64K bytes in size. The message body data can include pointers to other 
data blocks of any size. 

Messages are always sent to a predetermined destination port. At a port, incoming messages are queued in a 
first-in-first-out (FIFO) order. There are no system restrictions on the number of ports or the number of messages 
that may be queued to a port (other than the amount of available system memory). 

Messages are always queued by reference, i.e., by a pointer to the message. For performance reasons message 
copying is not performed. In essence, a message between two tasks is a temporary license for the receiving task 
to use a portion of the memory space of the sending task; that portion being the message itself. This means that 
if task A sends a message to task B, the message is still part of the task A context. Task A, however, should not 
access the message until it has been replied; that is, until task B has sent the message back, using the 
ReplyMsg() function. This technique of message exchange imposes important restrictions on message access. 

Message Ports 

Message ports are rendezvous points at which messages are collected. A port may contain any number of 
outstanding messages from many different originators. When a message arrives at a port, the message is 
appended to the end of the list of messages for that port, and a prespecified arrival action is invoked. This action 
may do nothing, or it may cause a predefined task signal or software interrupt (see the "Exec Interrupts" chapter). 

Exec Messages and Ports 499 

Like many Exec structures, ports may be given a symbolic name. Such names are particularly useful for tasks 
that must rendezvous with dynamically created ports. They are also useful for debugging purposes. 

A message port consists of a MsgPort structure as defined in the <exec/ports.h> and <exec/ports.i> include files. 
The C structure for a port is as follows: 

struct MsgPort { 

struct Node mp_Node; 

UBYTE mp_Flags; 

TJBYTE mp_SigBit; 

void *mp_SigTask; 

struct List mp_MsgList ; 

} ; 

mp_Node 

is a standard Node structure. This is useful for tasks that might want to rendezvous with a particular 
message port by name. 

mp_Flags 

are used to indicate message arrival actions. See the explanationbelow. 

mp_SigBit 

is the signal bit numberwhen a port is used with the task signal arrival action. 



mp_SigTask 

is a pointer to the task to be signaled. If a software interrupt arrival action is specified, this is a pointer 
to the interrupt structure. 

mp_MsgList 

is the list header for all messages queued to this port. (See the "Exec Lists and Queues" chapter). 

The mp_Flags field contains a subfield indicated by the PF_ACTION mask. This sub-field specifies the message 
arrival action that occurs when a port receives a new message. The possibilities are as follows: 

PA_SIGNAL 

This flag tells Exec to signal the mp_SigTask using signal number mp SigBit on the arrival of a new 
message. Every time a message is put to the port another signal will occur regardless of how many 
messages have been queued to the port. 

PA_SOFTINT 

This flag tells Exec to CauseQ a software interrupt when a message arrives at the port. In this case, 
the mp_SigTask field must contain a pointer to a struct Interrupt rather than a Task pointer. The 
software interrupt will be Caused every time a message is received. 

PAJGNORE 

This flag tells Exec to perform no operation other than queuing the message. This action is often used 
to stop signaling or software interrupts without disturbing the contents of the mp_SigTask field. 

It is important to realize that a port's arrival action will occur for each new message queued, and that there is not a 
one-to-one correspondence between messages and signals. Task signals are only single-bit flags so there is no 
record of how many times a particular signal occurred. There may be many messages queued and only a single 
task signal; sometimes however there may be a signal, but no messages. All of this has certain implications when 
designing code that deals with these actions. Your code should not depend on receiving a signal for every 
message at your port. All of this is also true for software interrupts. 
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Creating a Message Port 

To create a new message port using an operating system release prior to V36, you must allocate and initialize a 
MsgPort structure. If you want to make the port public, you will also need to call the AddPort() function. Don't 
make a port public when it is not necessary for it to be so. The easiest way to create a port is to use the amiga.lib 
function CreatePort(name, priority). If NULL is passed for the name, the port will not be made public. Port 
structure initialization involves setting up a Node structure, establishing the message arrival action with its 
parameters, and initializing the list header. The following example of port creation is equivalent to the 
CreatePort() function as supplied in amiga.lib: 

struct MsgPort *CreatePort (TJBYTE *name, LONG pri) 

{ 

LONG sigBit; 
struct MsgPort *mp; 

if ((sigBit = AllocSignal (-1L) ) == -1) return (NULL) ; 

mp = (struct MsgPort *) AllocMem ( (ULONG) sizeof (struct MsgPort ), (DLONG) MEMF_PUBLIC | MEMF_CLEAR) ; 

if (Imp) 

{ 

FreeSignal (sigBit) ; 
return (NULL) ; 

} 

mp->mp_Node . ln_Name = name; 

mp->mp_Node . ln_Pri = pri; 

mp->mp_Node. ln_Type = NT_MSGPORT; 

mp - >mp_F lags = PA_S I GNAL ; 

mp->mp_SigBit = sigBit; 

mp->mp_SigTask = (struct Task *) FindTask (0L) ; 

/* Find THIS task. */ 



if (name) AddPort (mp) ; 
else NewList (& (mp->mp_MsgList) 



/* init message list */ 



return (mp) 



As of V36 the Exec CreateMsgPort() function can be used to create a message port. This function allocates and 
initializes a new message port. Just like CreatePort(), a signal bit will be allocated and the port will be initialized 
to signal the creating task (mp_SigTask) when a message arrives at this port. To make the port public after 
CreateMsgPort(), you must fill out the ln_Name field and call AddPort(). If you do this, you must remember to 
RemPortO the port from the public list in your cleanup. If you need to create a message port and your application 
already requires Release 2 or greater, you can use CreateMsgPort() instead of CreatePort(). The following is an 
example of the usage of CreateMsgPort(). 

struct MsgPort *newmp; 

/* A private message port has been created. CreateMsgPort ( ) */ 
if (newmp = CreateMsgPort () ) 

/* returns NULL if the creation of the message port failed. */ 



newmp - >mp_Node . ln_Name 
newmp- >mp_Node . ln_Pri 
AddPort (newmp) ; 



"Griffin" ; 

0; /* To make it public fill in the fields */ 
/* with appropriate values. */ 



Deleting a Message Port 

Before a message port is deleted, all outstanding messages from other tasks must be returned. This is done by 
getting and replying to all messages at the port until message queue is empty. Of course, there is no need to 
reply to messages owned by the current task (the task performing the port deletion). Public ports attached to the 
system with AddPort() must be removed from the system with RemPortQ before deallocation. This amiga.lib 
functions CreatePortQ and DeletePortQ handle this automatically. 
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The following example of port deletion is equivalent to the DeletePortQ function as supplied in amiga.lib. 
that DeletePortQ must only be used on ports created with CreatePortQ. 



Note 



void DeletePort (mp) 
struct MsgPort *mp; 

{ 

if ( mp->mp_Node . ln_Name ) RemPort (mp) ; /* if it was public. 



*/ 



mp->mp_SigTask = (struct Task *) -1; /* Make it difficult to re-use the port */ 
mp->mp_MsgList . lh_Head = (struct Node *) -1; 

FreeSignal ( mp->mp_SigBit ); 
FreeMem ( mp, (ULONG) sizeof (struct MsgPort) ); 
} 

To delete ports created with CreateMsgPort(), DeleteMsgPort() must be used. Note that these functions are 
only available in V36 and higher. If the port was made public with AddPortQ, RemPort() must be used first, to 
remove the port from the system. Again, make sure all outstanding messages are replied to, so that the message 
queue is empty. 



struct MsgPort *newmp; 

if (newmp) 

{ 

if ( newmp- >mp_Node . ln_Name ) RemPort (newmp) ; /* if it was public... */ 
DeleteMsgPort (newmp) ; 



How to Rendezvous at a Message Port 

The FindPort() function provides a means of finding the address of a public port given its symbolic name. For 
example, FindPort("Griffin") will return either the address of the message port named "Griffin" or NULL 
indicating that no such public port exists. Since FindPortQ does not do any arbitration over access to public 
ports, the usage of FindPort() must be protected with Forbid()/Permit(). Names should be unique to prevent 
collisions among multiple applications. It is a good idea to use your application name as a prefix for your port 
name. FindPort() does not arbitrate for access to the port list. The owner of a port might remove it at any time. 
For these reasons a Forbid()/Permit() pair is required for the use of FindPort(). The port address can no longer 
be regarded as being valid after Permit() unless your application knows that the port cannot go away (for 
example, if your application created the port). 

The following is an example of how to safely put a message to a specific port: 

#include <exec/types . h> 
#include <exec/ports . h> 

BOOL MsgPort SafePutToPort (struct Message *message, STRPTR portname) 

{ 

struct MsgPort *port; 

Forbid ( ) ; 
port = FindPort (portname) ; 
if (port) PutMsg (port , message) ; 
Permit ( ) ; 
return(port ? TRUE : FALSE); /* If FALSE, the port was not found */ 

/* Once we've done a Permit!) , the port might go away */ 
/* and leave us with an invalid port address. So we */ 
/* return just a BOOL to indicate whether the message */ 
/* has been sent or not. */ 

} 
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Messages 

As mentioned earlier, a message contains both system header information and the actual message content. The 
system header is of the Message form defined in <exec/ports.h> and <exec/ports.i>. In C this structure is as 
follows: 

struct Message { 

struct Node mn_Node; 
struct MsgPort *mn_ReplyPort ; 
UWORD mn_Length; 

}; 

mn Node 

is a standard Node structure used for port linkage. 

mn ReplyPort 

is used to indicate a port to which this message will be returned when a reply is necessary. 

mn_Length 

indicates the total length of the message, including the Message structure itself. 

This structure is always attached to the head of all messages. For example, if you want a message structure that 
contains the x and y coordinates of a point on the screen, you could define it as follows: 

struct XYMessage { 

struct Message xy_Msg; 
UWORD xy_X ; 

UWORD xy_Y ; 



} 

For this structure, the mn_Length field should be set to sizeof(struct XYMessage). 

Putting a Message 

A message is delivered to a given destination port with the PutMsg() function. The message is queued to the 
port, and that port's arrival action is invoked. If the action specifies a task signal or a software interrupt, the 
originating task may temporarily lose the processor while the destination processes the message. If a reply to the 
message is required, the mn_ReplyPort field must be set up prior to the call to PutMsg(). 

Here is a code fragment for putting a message to a public port. A complete example is printed at the end of the 
chapter. 

#include <exec/types . h> 
#include <exec/memory.h> 
#include <exec/ports . h> 
#include <libraries/dos .h> 

VOID main (VOID) ; 

BOOL SafePutToPort (struct Message *, STRPTR) ; 

struct XYMessage { 

struct Message xy_Msg; 
UWORD xy_X ; 

UWORD xy_Y ; 

}; 
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VOID main (VOID) 

{ 

struct MsgPort *xyport, *xyreplyport ; 
struct XYMessage *xymsg, *msg; 
BOOL f oundport ; 

/* Allocate memory for the message we're going to send. */ 

if (xymsg = (struct XYMessage *) AllocMem (sizeof (struct XYMessage), MEMF_PUBLIC | MEMF_CLEAR) ) 
{ 

/* The replyport we'll use to get response */ 

if (xyreplyport = CreateMsgPort ( ) ) { /* or use CreatePort (0 , 0) */ 

xymsg- >xy_Msg. mn_Node . ln_Type = NT_MESSAGE; /* Compose the message */ 
xymsg- >xy_Msg.mn_Length = sizeof (struct XYMessage); 
xymsg- >xy_Msg.mn_ReplyPort = xyreplyport; 
xymsg- >xy_X = 10; 
xymsg- >xy_Y = 20; 

/* Now try to send that message to a public port named 

* "xyport". If foundport eq 0, the port isn't out there. 

*/ 

if (foundport = SafePutToPort ( (struct Message *)xymsg, "xyport")) 

{ 

. . . /* Now let's wait till the someone responds... */ 

} 

else printf ( "Couldn' t find ' xyport ' \n" ) ; 

DeleteMsgPort (xyreplyport) ; /* Use DeletePortO if */ 

/* the port was created */ 
} /* with CreatePort () . */ 

else printf ( "Couldn' t create message port\n"); 
FreeMem (xymsg, sizeof (struct XYMessage)); 



else printf ( "Couldn' t get memory for xymessage\n" ) ; 
} 

Waiting for a Message 

A task may go to sleep waiting for a message to arrive at one or more ports. This technique is widely used on the 
Amiga as a general form of event notification. For example, it is used extensively by tasks for I/O request 
completion. 

The MsgPort.mp_SigTask field contains the address of the task to be signaled and mp_SigBit contains a 
preallocated signal number (as described in the "Exec Tasks" chapter). 

You can call the WaitPortQ function to wait for a message to arrive at a port. This function will return the first 
message (it may not be the only) queued to a port. Note that your application must still call GetMsgO to remove 
the message from the port. If the port is empty, your task will go to sleep waiting for the first message. If the port 
is not empty, your task will not go to sleep. It is possible to receive a signal for a port without a message being 
present yet. The code processing the messages should be able to handle this. The following code illustrates 
WaitPort(). 

struct XYMessage *xy_msg; 
struct MsgPort *xyport; 

xyport = CreatePort ( "xyport " , 0) ; 
if (xyport == 0) 

{ 

printf ( "Couldn' t create xyport\n"); 

exit (31) ; 
} 

xy_msg = WaitPort (xyport) ; /* go to sleep until message arrives */ 
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A more general form of waiting for a message involves the use of the WaitQ function (see the "Exec Signals" 
chapter). This function waits for task event signals directly. If the signal assigned to the message port occurs, the 
task will awaken. Using the WaitQ function is more general because you can wait for more than one signal. By 
combining the signal bits from each port into one mask for the Wait() function, a loop can be set up to process all 
messages at all ports. 

Here's an example using Wait(): 

struct XYMessage *xy_msg; 
struct MsgPort *xyport; 
ULONG usersig, portsig; 
BOOL ABORT = FALSE; 

if (xyport = CreatePort ( "xyport " , 0)) 

{ 

portsig = 1 << xyport->mp_SigBit ; 

usersig = SIGBREAKF_CTRL_C; /* User can break with CTRL-C. */ 

for ( ; ; ) 

{ 

signal = Wait (portsig | usersig); /* Sleep till someone signals. */ 

if (signal & portsig) /* Got a signal at the msgport . */ 

{ • • • 

} 

if (signal & usersig) /* Got a signal from the user. */ 

{ 

ABORT = TRUE; /* Time to clean up. */ 

} 

if (ABORT) break; 



DeletePort (xyport) ; 

} 

else printf ( "Couldn' t create xyport\n"); 

WaitPort() Does Not Remove A Message. WaitPortQ only returns a pointer to the first 
message in a port. It does not actually remove the message from the port queue. 

Getting a Message 

Messages are usually removed from ports with the GetMsg() function. This function removes the next message 
at the head of the port queue and returns a pointer to it. If there are no messages in a port, this function returns a 
zero. 

The example below illustrates the use of GetMsg() to print the contents of all messages in a port: 

while (xymsg = GetMsg (xyport) ) printf ( "x=%ld y=%ld\n", xymsg->xy_X, xymsg->xy_Y) ; 

Certain messages may be more important than others. Because ports impose FIFO ordering, these important 
messages may get queued behind other messages regardless of their priority. If it is necessary to recognize 
more important messages, it is easiest to create another port for these special messages. 

Replying 

When the operations associated with receiving a new message are finished, it is usually necessary to send the 
message back to the originator. The receiver replies the message by returning it to the originator using the 
ReplyMsg() function. This is important because it notifies the originator that the message can be reused or 
deallocated. The ReplyMsgQ function serves this purpose. It returns the message to the port specified in the 
mn_ReplyPort field of the message. If this field is zero, no reply is returned. 
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The previous example can be enhanced to reply to each of its messages: 

while (xymsg = GetMsg (xyport) ) { 

printf ( "x=%ld y=%ld\n", xymsg->xy_X, xymsg- >xy_Y) ; 
ReplyMsg (xymsg) ; 
} 

Notice that the reply does not occur until after the message values have been used. 

Often the operations associated with receiving a message involve returning results to the originator. Typically this 
is done within the message itself. The receiver places the results in fields defined (or perhaps reused) within the 
message body before replying the message back to the originator. Receipt of the replied message at the 
originator's reply port indicates it is once again safe for the originator to use or change the values found within the 
message. 

The following are two short example tasks that communicate by sending, waiting for and replying to messages. 
Run these two programs together. 

PoM.c 

;/* portl.c - Execute me to compile with SAS C 5.10 

LC -bl -cfistq -v -y - j 73 portl.c 

Blink FROM LIB : c . o, portl . o TO portl LIBRARY LIB : LC . lib, LIB : Amiga . lib 

quit 

* portl.c - port and message example, run at the same time as port2.c 
*/ 

#include <exec/types . h> 
#include <exec/ports . h> 
#include <dos/dos.h> 
#include <clib/exec_protos . h> 
#include <clib/alib_protos . h> 



#include <stdio.h> 

#ifdef LATTICE 

int CXBRK(void) { return(O); } /* Disable Lattice CTRL-C handling */ 

int chkabort (void) {return (0) ; } 

#endif 

struct XYMessage { 

struct Message xym_Msg; 
WORD xy_X ; 

WORD xy_Y ; 

}; 

void main (int argc, char **argv) 

{ 

struct MsgPort *xyport; 
struct XYMessage *xymsg; 
ULONG portsig, usersig, signal; 
BOOL ABORT = FALSE; 

if (xyport = CreatePort ( "xyport " , 0)) 

{ 

portsig = 1 << xyport - >mp_SigBit ; /* Give user a 'break' signal. */ 
usersig = SIGBREAKF_CTRL_C; 

printf ( "Start port2 in another shell. CTRL-C here when done.\n"); 
do 

{ /* portl will wait forever and reply */ 

signal = Wait (portsig | usersig) ; /* to messages, until the user breaks. */ 

/* Since we only have one port that might get messages we */ 
if (signal & portsig) /* have to reply to, it is not really necessary to test for */ 
{ /* the portsignal. If there is not message at the port, xymsg */ 

while (xymsg = (struct XYMessage *) GetMsg (xyport) ) /* simply will be NULL. */ 

{ 

printf ( "portl received: x = %d y = %d\n", xymsg->xy_X, xymsg - >xy_Y ) ; 

xymsg->xy_X += 50; /* Since we have not replied yet to the owner of */ 
xymsg->xy_Y += 50; /* xymsg, we can change the data contents of xymsg. */ 



} 
} 



printf ( "portl replying with: x = %d y = %d\n", xymsg->xy_X, xymsg- >xy_Y) ; 
ReplyMsg ( (struct Message *)xymsg); 



if (signal & usersig) /* The user wants to abort. */ 

{ 

while (xymsg = (struct XYMessage *) GetMsg (xyport) ) /*Make sure port is empty. */ 

ReplyMsg ( (struct Message *)xymsg); 
ABORT = TRUE; 
} 
} 

while (ABORT == FALSE) ; 
DeletePort (xyport) ; 

} 
else printf ( "Couldn' t create 'xyport ' \n" ) ; 

} 

Port2.c 

;/* port2.c - Execute me to compile me with SAS C 5.10 

LC -bl -cfistq -v -y - j 73 port2.c 

Blink FROM LIB : c . o, port2 . o TO port2 LIBRARY LIB : LC . lib, LIB : Amiga . lib 

quit 

** port2.c - port and message example, run at the same time as portl. c 
*/ 

#include <exec/types . h> 
#include <exec/ports . h> 
#include <exec/memory . h> 



#include <dos/dos.h> 
#include <clib/exec_protos . h> 
#include <clib/alib_protos . h> 
#include <stdio.h> 

#ifdef LATTICE 

int CXBRK(void) { return(O); } /* Disable Lattice CTRL-C handling */ 

int chkabort (void) {return (0) ; } 

#endif 

BOOL SafePutToPort (struct Message *, STRPTR) ; 

struct XYMessage { 

struct Message xy_Msg; 
WORD xy_X ; 

WORD xy_Y ; 

}; 

void main (int argc, char **argv) 

{ 

struct MsgPort *xyreplyport ; 
struct XYMessage *xymsg, *reply; 

/* Using CreatePortO with no name */ 
if (xyreplyport = CreatePort (0, 0) ) /* because this port need not be public. */ 

{ 

if (xymsg = (struct XYMessage *) AllocMem (sizeof (struct XYMessage), MEMF_PUBLIC | MEMF_CLEAR) ) 

{ 

xymsg - >xy_Msg. mn_Node . ln_Type = NT_MESSAGE; /* make up a message, */ 
xymsg- >xy_Msg.mn_Length = sizeof (struct XYMessage); /*including the reply port. */ 
xymsg - >xy_Msg . mn_ReplyPort = xyreplyport; 

xymsg->xy_X = 10; /* our special message information. */ 

xymsg- >xy_Y = 20; 

printf ( "Sending to portl: x = %d y = %d\n", xymsg->xy_X, xymsg- >xy_Y) ; 

/* port2 will simply try to put */ 

if (SafePutToPort ( (struct Message *)xymsg, "xyport")) 

/* one message to portl wait for */ 
{ /* the reply, and then exit */ 

WaitPort (xyreplyport) ; 
if (reply = (struct XYMessage *) GetMsg (xyreplyport) ) 

printf ( "Reply contains: x = %d y = %d\n", /* We don't ReplyMsg since */ 
xymsg->xy_X, xymsg- >xy_Y) ; /* WE initiated the message. */ 

/* Since we only use this private port for receiving replies, and we sent */ 

/* only one and got one reply there is no need to cleanup. For a public port, */ 

/* or if you pass a pointer to the port to another process, it is a very good */ 

/* habit to always handle all messages at the port before you delete it. */ 

} 

else printf ( "Can' t find 'xyport'; start portl in a separate shell\n"); 

FreeMem (xymsg, sizeof (struct XYMessage)); 

} 

else printf ( "Couldn' t get memory\n"); 
DeletePort (xyreplyport) ; 

} 

else printf ( "Couldn' t create xyreplyport \n" ) ; 



} 

BOOL SafePutToPort (struct Message 'message, STRPTR portname) 

{ 

struct MsgPort *port; 

Forbid ( ) ; 

port = FindPort (portname) ; 

if (port) PutMsgtport, message); 

Permit ( ) ; 

return (port ? TRUE : FALSE); /* FALSE if the port was not found */ 

/* Once we've done a Permit () , the port might go away and leave us with an invalid port */ 
} /*address. So we return just a BOOL to indicate whether the message has been sent or not. */ 



Function Reference 



The following chart gives a brief description of the Exec functions that control inter-task communication with 
messages and ports. See the Amiga ROM Kernel Reference Manual: Includes and Autodocs for details about 
each call. 

Table 24-1 : Exec Message and Port Functions 



Function 


Description 


AddPort() 


Add a public message port to the system list. 


CreateMsgPort() 


Allocate and initialize a new message port (V37). 


DeleteMsg Port() 


Free a message port, created with CreateMsgPort() (V37). 


FindPort() 


Find a public message port in the system list. 


GetMsg() 


Get next message from the message port. 


PutMsg() 


Put a message to a message port. 


RemPort() 


Remove a message port from the system list. 


ReplyMsg() 


Reply to a message on its reply port. 



Table 24-2: Amiga.lib Exec Support Functions 



Function 



Description 



CreatePort() 
DeletePortQ 



Allocate and initialize a new message port, make public if named 
Delete a message port, created with CreatePort(). 



Chapter 25 

Exec Semaphores 



Semaphores are a feature of Exec which provide a general method for tasks to arbitrate for the use of memory or 
other system resources they may be sharing. This chapter describes the structure of Exec semaphores and the 
various support functions provided for their use. Since the semaphore system uses Exec lists and signals, some 
familiarity with these concepts is helpful for understanding semaphores. 

In any multitasking or multi-processing system there is a need to share data among independently executing 
tasks. If the data is static (that is, it never changes), then there is no problem. However, if the data is variable, 
then there must be some way for a task that is about to make a change to keep other tasks from looking at the 
data. 

For example, to add a node to a linked list of data, a task would normally just add the node. However, if the list is 
shared with other tasks, this could be dangerous. Another task could be walking down the list while the change is 
being made and pick up an incorrect pointer. The problem is worse if two tasks attempt to add an item to the list 
at the same time. Exec semaphores provide a way to prevent such problems. 

A semaphore is much like getting a key to a locked data item. When you have the key (semaphore), you can 
access the data item without worrying about other tasks causing problems. Any other tasks that try to obtain the 
semaphore will be put to sleep until the semaphore becomes available. When you have completed your work with 
the data, you return the semaphore. 

For semaphores to work correctly, there are two restrictions that must be observed at all times: 

1 ) All tasks using shared data that is protected by a semaphore must always ask for the semaphore first 
before accessing the data. If some task accesses the data directly without first going through the 
semaphore, the data may be corrupted. No task will have safe access to the data. 

2) A deadlock will occur if a task that owns an exclusive semaphore on some data inadvertently calls 
another task which tries to get an exclusive semaphore on that same data in blocking mode. Deadlocks 
and other such issues are beyond the scope of this manual. For more details on deadlocks and other 
problems of shared data in a multitasking system and the methods used to prevent them, refer to a 
textbook in computer science such as Operating Systems by Tannenbaum (Prentice-Hall). 
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Semaphore Functions 

Exec provides a variety of useful functions for setting, checking and freeing semaphores. The prototypes for 
these functions are as follows. 

VOID AddSemaphore ( struct SignalSemaphore *sigSem ) ; 
ULONG AttemptSemaphore ( struct SignalSemaphore *sigSem ) ; 
struct SignalSemaphore *FindSemaphore ( UBYTE *sigSem ); 
VOID InitSemaphore ( struct SignalSemaphore *sigSem ) ; 

VOID ObtainSemaphore ( struct SignalSemaphore *sigSem ) ; 

VOID ObtainSemaphoreList ( struct List *sigSem ) ; 

void ObtainSemaphoreShared ( struct SignalSemaphore *sigSem ); 

VOID ReleaseSemaphore ( struct SignalSemaphore *sigSem ); 
VOID ReleaseSemaphoreList ( struct List *sigSem ) ; 
VOID RemSemaphore ( struct SignalSemaphore *sigSem ); 

The Signal Semaphore 

Exec semaphores are signal based. Using signal semaphores is the easiest way to protect shared, single-access 



resources in the Amiga. Your task will sleep until the semaphore is available for use. The SignalSemaphore 
structure is as follows: 

struct SignalSemaphore { 

struct Node ss_Link; 

SHORT ss_Nest Count; 

struct MinList ss_WaitQueue; 

struct SemaphoreRequest ss_MultipleLink; 

struct Task *ss_Owner; 

SHORT ss_QueueCount; 

}; 

ss_Link 

is the node structure used to link semaphores together. The InPri and ln_Name fields are used to set 
the priority of the semaphore in a list and to name the semaphore for public access. If a semaphore is 
not public the ln_Name and ln_Pri fields may be left NULL. 

ss_NestCount 

is the count of number of locks the current owner has on the semaphore. 

ss_WaltQueue 

is the List header for the list of other tasks waiting for this semaphore. 

ss_MultlpleLink 

is the SemaphoreRequest used by ObtainSemaphoreList(). 

ss_Owner 

is the pointer to the current owning task. 

ss_QueueCount 

is the number of other tasks waiting for the semaphore. 

A practical application of a SignalSemaphore would be to use it as the base of a shared data structure. For 
example: 

struct SharedList { 

struct SignalSemaphore sl_Semaphore; 
struct MinList sl_List; 

}; 
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Creating a SignalSemaphore Structure 

To initialize a SignalSemaphore structure use the lnitSemaphore() function. This function initializes the list 
structure and the nesting and queue counters. It does not change the semaphore's name or priority fields. 

This fragment creates and initializes a semaphore for a data item such as the SharedList structure above. 

struct SharedList *slist; 

if (slist= (struct SharedList *) 

AllocMem(sizeof (struct SharedList) , MEMF_PUBLIC | MEMF_CLEAR) ) 

{ 

NewList (&slist->sl_List) ; /* Initialize the MinList */ 
InitSemaphore ( (struct SignalSemaphore *)slist); 

/* And initialize the semaphore */ 
/* The semaphore can now be used. */ 

} 

else printf ( "Can' t allocate structure\n" ) ; 

Making a SignalSemaphore Available to the Public 

A semaphore should be used internally in your program if it has more than one task operating on shared data 
structures. There may also be cases when you wish to make a data item public to other applications but still need 



to restrict its access via semaphores. In that case, you would give your semaphore a unique name and add it to 
the public SignalSemaphore list maintained by Exec. The AddSemaphoreQ function does this for you. This 
works in a manner similar to AddPort() for message ports. 

To create and initialize a public semaphore for a data item and add it to the public semaphore list maintained by 
Exec, the following function should be used. (This will prevent the semaphore from being added or removed more 
than once by separate programs that use the semaphore). 

UBYTE *name; /* name of semaphore to add */ 
struct SignalSemaphore *semaphore; 

Forbid ( ) ; 
/* Make sure the semaphore name is unique */ 
if ( ! FindSemaphore (name) ) { 

/* Allocate memory for the structure */ 
if (sema= (struct SignalSemaphore *) 

AllocMem(sizeof (struct SignalSemaphore) , MEMF_PUBLIC | MEMF_CLEAR) ) 



{ 



sema->ss_Link. ln_Pri=0 ; /* Set the priority to zero */ 

sema->ss_Link. ln_Name=name; 

/* Note that the string 'name' is not copied. If that is */ 
/* needed, allocate memory for it and copy the string. And */ 
/* add the semaphore the the system list */ 

AddSemaphore (semaphore) ; 



Permit ( ) ; 

A value of NULL for semaphore means that the semaphore already exists or that there was not enough free 
memory to create it. 

Before using the data item or other resource which is protected by a semaphore, you must first obtain the 
semaphore. Depending on your needs, you can get either exclusive or shared access to the semaphore. 
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Obtaining a SignalSemaphore Exclusively 

The ObtainSemaphoreQ function can be used to get an exclusive lock on a semaphore. If another task currently 
has an exclusive or shared lock(s) on the semaphore, your task will be put to sleep until all locks on the the 
semaphore are released. 

Semaphore Nesting. SignalSemaphores have nesting. That is, if your task already owns the 
semaphore, it will get a second ownership of that semaphore. This simplifies the writing of 
routines that must own the semaphore but do not know if the caller has obtained it yet. 

To obtain a semaphore use: 

struct SignalSemaphore *semaphore; 
ObtainSemaphore (semaphore) ; 

To get an exclusive lock on a public semaphore, the following code should be used: 

UBYTE *name; 

struct SignalSemaphore *semaphore; 

Forbid () ; /* Make sure the semaphore will not go away if found. */ 
if (semaphore=FindSemaphore (name) ) 

ObtainSemaphore (semaphore) ; 
Permit ( ) ; 

The value of semaphore is NULL if the semaphore does not exist. This is only needed if the semaphore has a 
chance of going away at any time (i.e., the semaphore is public and might be removed by some other program). 
If there is a guarantee that the semaphore will not disappear, the semaphore address could be cached, and all 



that would be needed is a call to the ObtainSemaphoreQ function. 

Obtaining a Shared SignalSemaphore 

For read-only purposes, multiple tasks may have a shared lock on a signal semaphore. If a semaphore is already 
exclusively locked, all attempts to obtain the semaphore shared will be blocked until the exclusive lock is 
released. At that point, all shared locks will be obtained and the calling tasks will wake up. 

To obtain a shared semaphore, use: 

struct SignalSemaphore *semaphore; 
ObtainSemaphoreShared (semaphore) ; 

To obtain a public shared semaphore, the following code should be used: 

UBYTE *name; 

struct SignalSemaphore *semaphore; 

Forbid ( ) ; 

if (semaphore = FindSemaphore (name) ) 

ObtainSemaphoreShared (semaphore) ; 
Permit ( ) ; 
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Checking a SignalSemaphore 

When you attempt to obtain a semaphore with ObtainSemaphore(), your task will be put to sleep if the 
semaphore is not currently available. If you do not want to wait, you can call AttemptSemaphore() instead. If the 
semaphore is available for exclusive locking, AttemptSemaphore() obtains it for you and returns TRUE. If it is 
not available, the function returns FALSE immediately instead of waiting for the semaphore to be released. 

To attempt to obtain a semaphore, use the following: 

struct SignalSemaphore *semaphore; 
AttemptSemaphore (semaphore) ; 

To make an attempt to obtain a public semaphore, the following code should be used: 

UBYTE *name; 

struct SignalSemaphore *semaphore; 

Forbid ( ) ; 

if (semaphore = FindSemaphore (name) ) AttemptSemaphore (semaphore) ; 

Permit () ; 

Releasing a SignalSemaphore 

Once you have obtained the semaphore and completed any operations on the semaphore protected object, you 
should release the semaphore. The ReleaseSemaphore() function does this. For each successful 
ObtainSemaphore(), ObtainSemaphoreShared() and AttemptSemaphore() call you make, you must have a 
matching ReleaseSemaphore() call. 

Removing a SignalSemaphore Strucuture 

Semaphore resources can only be freed if the semaphore is not locked. A public semaphore should first be 
removed from the system semaphore list with the RemSemaphore() function. This prevents other tasks from 
finding the semaphore and trying to lock it. Once the semaphore is removed from the system list, the semaphore 
should be locked exclusively so no other task can lock it. Once the lock is obtained, it can be released again, and 
the resources can be deallocated. 

The following code should be used to remove a public semaphore: 



UBYTE *name; 

struct SignalSemaphore *semaphore; 

Forbid () ; 

if (semaphore=FindSemaphore (name) ) 

{ 

RemSemaphore (semaphore) ; /* So no one else can find it . . . */ 

ObtainSemaphore (semaphore) ; /* Wait for us to be last user...*/ 

ReleaseSemaphore (semaphore) ; /* Ready for cleanup... */ 

} 

FreeMem (semaphore, sizeof (struct SignalSemaphore)); 

Permit () ; 
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Multiple Semaphores 

The semaphore system has the ability to ask for ownership of a complete list of semaphores. This can help 
prevent deadlocks when there are two or more tasks trying to get the same set of semaphores. If task A gets 
semaphore 1 and tries to obtain semaphore 2 after task B has obtained semaphore 2 but before task B tries to 
obtain semaphore 1 then both tasks will hang. Exec provides ObtainSemaphoreList() and 
ReleaseSemaphoreList() to prevent this problem. 

A semaphore list is a list header to a list that contains SignalSemaphore structures. The semaphore list must 
not contain any public semaphores. This is because the semaphore list functions use the standard node 
structures in the semaphore. 

To arbitrate access to a semaphore list use another semaphore. Create a public semaphore and use it to 
arbitrate access to the list header of the semaphore list. This also gives you a locking semaphore, protecting the 
ObtainSemaphoreList() call. Once you have gained access to the list with ObtainSemaphore(), you may 
obtain all the semaphores on the list via ObtainSemaphoreList() (or get individual semaphores with 
ObtainSemaphore()). When you are finished with the protected objects, release the semaphores on the list with 
ReleaseSemaphoreList(), and then release the list semaphore via ReleaseSemaphore(). 

For example: 

ObtainSemaphore ( (struct SignalSemaphore *) SemaphoreList) ; 
ObtainSemaphoreList (SemaphoreList->sl_List) ; 

/* At this point the objects are protected, and can be manipulated */ 

ReleaseSemaphoreList (SemaphoreList->sl_List) ; 
ReleaseSemaphore ( (struct SignalSemaphore *) SemaphoreList) ; 

See the SharedList structure above for an example of a semaphore structure with a list header. 

Semaphore Example 

A simple "do nothing" example of Exec signal semaphore use is shown below. When the semaphore is owned by 
a task, attempted access by other tasks will block. A nesting count is maintained, so the current task can safely 
call ObtainSemaphore() on the same semaphore. 

/* A simple "do nothing" example of Exec signal semaphore use is shown */ 

/* below. When the semaphore is owned by a task, attempted access by */ 

/* other tasks will block. A nesting count is maintained, so the */ 

/* current task can safely call ObtainSemaphore ( ) on the same semaphore. */ 

/* 

/* semaphore. c - Exec semaphore example - compile with lc -L semaphore. c */ 
#include <exec/types .h> 
#include <exec/semaphores . h> 
#include <clib/exec_protos . h> 
#include <stdio.h> 

#ifdef LATTICE 

int CXBRK(void) { return(O); } /* Disable Lattice CTRL/C handling */ 



void chkabort (void) { return; } /* really */ 
#endif 

struct Signal Semaphore LockSemaphore = {o}; 

VOID main(int argc.char *argv[]) 

{ 

Ini t Semaphore (&LockSemaphore) ; 

ObtainSemaphore (&LockSemaphore) ; /* Task now owns the semaphore. */ 

ReleaseSemaphore (&LockSemaphore) ; /* Task has released the semaphore. */ 
} 
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The following charts give a brief description of the Exec semaphore functions. See the Amiga ROM Kernel 
Reference Manual: Includes and Autodocs for details about each call. 



Table 25-1 : Exec Semaphore Functions 



Exec Semaphore Function 



Description 



AddSemaphore() 

AttemptSemaphoreO 

FindSemaphore() 

lnitSemaphore() 

ObtainSemaphore() 

ObtainSemaphoreList() 

ObtainSemaphoreShared() 

ReleaseSemaphore() 

ReleaseSemaphoreList() 

RemSemaphore() 



Initialize and add a signal semaphore to the system. 

Try to get an exclusive lock on a signal semaphore without blocking. 

Find a given system signal semaphore. 

Initialize a signal semaphore. 

Try to get exclusive access to a signal semaphore. 

Try to get exclusive access to a list of signal semaphores. 

Try to get shared access to a signal semaphore (V36). 

Release the lock on a signal semaphore. 

Release the locks on a list of signal semaphores. 

Remove a signal semaphore from the system. 



Chapter 26 
Exec Interrupts 



Exec manages the decoding, dispatching, and sharing of all system interrupts. This includes control of hardware 
interrupts, software interrupts, task-relative interrupts (see the discussion of exceptions in the "Exec Tasks" 
chapter), and interrupt disabling and enabling. In addition, Exec supports a more extended prioritization of 
interrupts than that provided in the 68000. 

The proper operation of multitasking depends heavily on the consistent management of the interrupt system. 
Task activities are often driven by intersystem communication that is originated by various interrupts. 

Sequence of Events During an Interrupt 

Before useful interrupt handling code can be executed, a considerable amount of hardware and software activity 
must occur. Each interrupt must propagate through several hardware and software interfaces before application 
code is finally dispatched: 

A hardware device decides to cause an interrupt and sends a signal to the interrupt control portions of 
the 4703 (Paula) custom chip. 

The 4703 interrupt control logic notices this new signal and performs two primary operations. First, it 
records that the interrupt has been requested by setting a flag bit in the INTREQ register. Second, it 
examines the INTENA register to determine whether the corresponding interrupt and the interrupt master 
are enabled. If both are enabled, the 4703 generates an interrupt request by placing the priority level of 
the request onto the three 68000 interrupt control input lines (IPL0, IPL1, IPL2). 

These three signals correspond to seven interrupt priority levels in the 68000. If the priority of the new 
interrupt is grreaferthan the current processor priority, an interrupt sequence is initiated. The priority level 
of the new interrupt is used to index into the top seven words of the processor address space. The odd 
byte (a vector number) of the indexed word is fetched and then shifted left by two to create an offset into 
the processor's auto-vector interrupt table. The vector offsets used are in the range of $064 to $07C. 
These are labeled as interrupt autovectors in the 68000 manual. The auto-vector table appears in low 
memory on a 68000 system, but its location for other 68000 family processors is determined by the 
processor's CPU Vector Base Register (VBR). VBR can be accessed from supervisor mode with the 
MOVEC instruction. 
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The processor then switches into supervisor mode (if it is not already in that mode), and saves copies of 
the status register and program counter (PC) onto the top of the system stack (additional information 
may be saved by processors other than the 68000). The processor priority is then raised to the level of 
the active interrupt. 

From the low memory vector address (calculated in step three above), a 32-bit autovector address is 
fetched and loaded into the program counter. This is an entry point into Exec's interrupt dispatcher. 

Exec must now further decode the interrupt by examining the INTREQ and INTENA 4703 chip registers. 
Once the active interrupt has been determined, Exec indexes into an ExecBase array to fetch the 
interrupt's handler entry point and handler data pointer addresses. 

Exec now turns control over to the interrupt handler by calling it as if it were a subroutine. This handler 
may deal with the interrupt directly or may propagate control further by invoking interrupt server chain 
processing. 

You can see from the above discussion that the interrupt autovectors should never be altered by the user. If you 
wish to provide your own system interrupt handler, you must use the Exec SetlntVector() function. You should 
not change the contents of any autovector location. 

Task multiplexing usually occurs as the result of an interrupt. When an interrupt has finished and the processor is 



about to return to user mode, Exec determines whether task-scheduling attention is required. If a task was 
signaled during interrupt processing, the task scheduler will be invoked. Because Exec uses preemptive task 
scheduling, it can be said that the interrupt subsystem is the heart of task multiplexing. If, for some reason, 
interrupts do not occur, a task might execute forever because it cannot be forced to relinquish the CPU. 

Table 26-1 : Interrupts by Priority 



Hardware 
Priority 



1 



2 



3 



Exec 
Pseodo- 
Priority Description 



Label Type 



4 



5 



6 



7 



1 Serial transmit buffer empty 

2 disk block complete 

3 software interrupt 

4 external INT2 &. CIAA 

5 graphics coprocessor 

6 vertical blank interval 

7 blitter finished 

8 audio channel 2 

9 audio channel 

10 audio channel 3 

11 audio channel 1 

12 Serial receive buffer full 

13 disk sync pattern found 

14 external INT6 &. CIAB 

15 special (master enable) 
non-maskable interrupt 







TBE 


H 


DSKBLK 


H 


SOFTINT 


H 


PORTS 


S 


COPER 


S 


VERTB 


S 


BLIT 


H 


AUD2 


H 


AUDO 


H 


AUD3 


H 


AUDI 


H 


RBF 


H 


DSKSYNC 


H 


EXTER 


S 


INTEN 


- 


NMI 


S 
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Interrupt Priorities 



Interrupts are prioritized in hardware and software. The 68000 CPU priority at which an interrupt executes is 
determined strictly by hardware. In addition to this, the software imposes a finer level of pseudo-priorities on 
interrupts with the same CPU priority. These pseudo-priorities determine the order in which simultaneous 
interrupts of the same CPU priority are processed. Multiple interrupts with the same CPU priority but a different 
pseudo-priority will not interrupt one another. Interrupts are serviced by either an exclusive handler or by server 
chains to which many servers may be attached, as shown in the Type field of the table. The table above 
summarizes all interrupts by priority. 

The 8520s (also called CIAs) are Amiga peripheral interface adapter chips that generate the INT2 and INT6 
interrupts. For more information about them, see the Amiga Hardware Reference Manual. 

As described in the Motorola 68000 programmer's manual, interrupts may nest only in the direction of higher 
priority. Because of the time-critical nature of many interrupts on the Amiga, the CPU priority level must never be 
changed by user or system code. When the system is running in user mode (multitasking), the CPU priority level 
must remain set at zero. When an interrupt occurs, the CPU priority is raised to the level appropriate for that 
interrupt. Lowering the CPU priority would permit unlimited interrupt recursion on the system stack and would 
"short-circuit" the interrupt-priority scheme. 



Because it is dangerous on the Amiga to hold off interrupts for any period of time, higher-level interrupt code must 



perform its business and exit promptly. If it is necessary to perform a time-consuming operation as the result of a 
high-priority interrupt, the operation should be deferred either by posting a software interrupt or by signalling a 
task. In this way, interrupt response time is kept to a minimum. Software interrupts are described in a later 
section. 

Nonmaskable Interrupt 

The 68000 provides a nonmaskable interrupt (NMI) of CPU priority 7. Although this interrupt cannot be generated 
by the Amiga hardware itself, it can be generated on the expansion bus by external hardware. Because this 
interrupt does not pass through the 4703 interrupt controller circuitry, it is capable of violating system code critical 
sections. In particular, it short-circuits the DISABLE mutual-exclusion mechanism. Code that uses NMI must not 
assume that it can access system data structures. 



Servicing Interrupts 



Interrupts are serviced on the Amiga through the use of interrupt handlers and servers. An interrupt handler is a 
system routine that exclusively handles all processing related to a particular 4703 interrupt. An interrupt server is 
one of possibly many system routines that are invoked as the result of a single 4703 interrupt. Interrupt servers 
provide a means of interrupt sharing. This concept is useful for general-purpose interrupts such as vertical 
blanking. 

At system start, Exec designates certain interrupts as handlers and others as server chains. The PORTS, 
COPER, VERTB, EXTER, and NMI interrupts are initialized as server chains. Therefore, each of these may 
execute multiple interrupt routines per each interrupt. All other interrupts are designated as handlers and are 
always used exclusively. 
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Interrupt Data Structure 

Interrupt handlers and servers are defined by the Exec Interrupt structure. This structure specifies an interrupt 
routine entry point and data pointer. The C definition of this structure is as follows: 

struct Interrupt 

{ 

struct Node is_Node; 
APTR is_Data; 
VOID (*is_Code) () ; 

}; 
Once this structure has been properly initialized, it can be used for either a handler or a server. 

Environment 

Interrupts execute in an environment different from that of tasks. All interrupts execute in supervisor mode and 
utilize the single system stack. This stack is large enough to handle extreme cases of nested interrupts (of higher 
priorities). Interrupt processing has no effect on task stack usage. 

All interrupt processing code, both handlers and servers, is invoked as assembly code subroutines. Normal 
assembly code register conventions dictate that the DO, D1 , A0 and A1 registers be free for scratch use. In the 
case of an interrupt handler, some of these registers also contain data that may be useful to the handler code. 
See the section on handlers below. 

Because interrupt processing executes outside the context of most system activities, certain data structures will 
not be self-consistent and must be considered off limits for all practical purposes. This happens because certain 
system operations are not atomic in nature and might be interrupted only after executing part of an important 
instruction sequence. For example, memory allocation and deallocation routines do not disable interrupts. This 
results in the possibility of interrupting a memory-related routine. In such a case, a memory linked list may be 
inconsistent during and interrupt. Therefore, interrupt routines must not use any memory allocation or deallocation 
functions. 

In addition, interrupts may not call any system function which might allocate memory, wait, manipulate 
unprotected lists, or modify ExecBase->ThisTask data (for example Forbid(), PermitQ, and mathieee libraries). 



In practice, this means that very few system calls may be used within interrupt code. The following functions may 
generally be used safely within interrupts: 

Alert () , Disable (), Enable!) , Signal (), Cause () , 
GetMsgO, PutMsg ( ) , ReplyMsg ( ) , FindPort ( ) , FindTask ( ) 

and if you are manipulating your own List structures while in an interrupt: 

AddHead ( ) , AddTail ( ) , RemHead ( ) , RemTail ( ) , FindName ( ) 

In addition, certain devices (notably the timer device) specifically allow limited use of SendlOQ and BeginlO() 
within interrupts. 
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Interrupt Handlers 

As described above, an interrupt handler is a system routine that exclusively handles all processing related to a 
particular 4703 interrupt. There can only be one handler per 4703 interrupt. Every interrupt handler consists of an 
Interrupt structure (as defined above) and a single assembly code routine. Optionally, a data structure pointer 
may also be provided. This is particularly useful for ROM-resident interrupt code. 

An interrupt handler is passed control as if it were a subroutine of Exec. Once the handler has finished its 
business, it must return to Exec by executing an rts (return from subroutine) instruction rather than an RTE 
(return from exception) instruction. Interrupt handlers should be kept very short to minimize service-time overhead 
and thus minimize the possibilities of interrupt overruns. As described above, an interrupt handler has the normal 
scratch registers at its disposal. In addition, A5 and A6 are free for use. These registers are saved by Exec as 
part of the interrupt initiation cycle. 

For the sake of efficiency, Exec passes certain register parameters to the handler (see the list below). These 
register values may be utilized to trim a few microseconds off the execution time of a handler. All of the following 
registers (D0/D1/A0/A1/A5/A6) may be used as scratch registers by an interrupt handler, and need not be 
restored prior to returning. 

Don't Make Assumptions About Registers. Interrupt servers have different register usage rules 
(see the "Interrupt Servers" section). 

Interrupt Handler Register Usage 

Here are the register conventions for interrupt handlers. 

DO Contains no valid information. 

D1 Contains the 4703 INTENAR and INTREQR registers values AND'ed together. This results in an 

indication of which interrupts are enabled and active. 

A0 Points to the base address of the Amiga custom chips. This information is useful for performing indexed 

instruction access to the chip registers. 

A1 Points to the data area specified by the is_Data field of the Interrupt structure. Because this pointer is 

always fetched (regardless of whether you use it), it is to your advantage to make some use of it. 

A5 Is used as a vector to your interrupt code. 

A6 Points to the Exec library base (SysBase). You may use this register to call Exec functions or set it up 

as a base register to access your own library or device. 

Interrupt handlers are established by passing the Exec function SetlntVector(), your initialized Interrupt 
structure, and the 4703 interrupt bit number of interest. The parameters for this function are as follows: 

SetlntVector (ULONG intNumber, struct Interrupt *interrupt) 

The first argument is the bit number for which this interrupt server is to respond (example INTB_VERTB). The 
possible bits for interrupts are defined in <hardware/intbits.h>. The second argument is the address of an 



interrupt server node as described earlier in this chapter. Keep in mind that certain interrupts are established as 
server chains and should not be accessed as handlers. 
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The following example demonstrates initialization and installation of an assembler interrupt handler. See the 
"Resources" chapter for more information on allocating resources, and the "Serial Device" chapter in the Amiga 
ROM Kernel Reference Manual: Devices for the more common method of serial communications. 

;/* rbf . c - Execute me to compile me with SAS C 5.10 

LC -do -bl -cfistq -v -y - j 73 rbf . c 

Blink FROM LIB : c . o, rbf . o, rbf handler . o TO rbf LIBRARY LIB : LC . lib, LIB : Amiga . lib 

quit 

** rbf.c - serial receive buffer full interrupt handler example. 
** Must be linked with assembler handler rbfhandler.o 
• * 

** To receive characters, this example requires ASCII serial input 
** at your Amiga's current serial hardware baud rate (ie. 9600 after 
** reboot, else last baud rate used) 
*/ 

#include <exec/execbase .h> 
#include <exec/memory . h> 
#include <exec/interrupts . h> 
#include <resources/misc . h> 
#include <hardware/custom.h> 
#include <hardware/intbits . h> 
#include <dos/dos.h> 

#include <clib/exec_protos . h> 
#include <clib/misc_protos . h> 

#include <stdio.h> 
#include <string.h> 



#ifdef LATTICE 

int CXBRK(void) { return(O); } /* 

void chkabort (void) { return; } /* 

#endif 



Disable Lattice CTRL/C handling */ 
really */ 



#define BUFFERSIZE 256 

extern void RBFHandler ( ) ; /* proto for asm interrupt handler */ 
void main (void) ; 



struct MiscResource *MiscBase; 
extern struct ExecBase *SysBase; 
extern struct Custom far custom; 



/* defined in amiga.lib */ 



static UBYTE *allocname = "rbf -example" 

struct RBFData { 

struct Task *rd_Task; 

ULONG rd_Signal; 

ULONG rd_BufferCount; 

UBYTE rd_CharBuffer [BUFFERSIZE + 2] 

UBYTE rd_FlagBuffer [BUFFERSIZE + 2] 

UBYTE rd_Name[32]; 

}; 



void main (void) 

{ 

struct RBFData *rbfdata; 

UBYTE *currentuser; 

BYTE signr; 

struct Device *serdevice; 

struct Interrupt * rbf int, 

BOOL priorenable; 

ULONG signal; 



*priorint ; 



if (MiscBase = OpenResource ( "misc . resource" ) ) 

{ 

currentuser = AllocMiscResource (MR_SERIALPORT, allocname) ; /* Allocate the serial */ 
if (currentuser) /* port registers. */ 

{ 

printf ( "serial hardware allocated by %s. Trying to remove it\n", 

currentuser) ; /* Hey! someone got it! */ 

Forbid ( ) ; 
if (serdevice = (struct Device *) FindName (&SysBase->DeviceList , currentuser)) 

RemDevice (serdevice) ; 
Permit ( ) ; 

currentuser = AllocMiscResource (MR_SERIALPORT, allocname); /* and try again */ 

} 

if (currentuser == NULL) 

{ /* Get the serial */ 

currentuser = AllocMiscResource (MR_SERIALBITS, allocname); /* control bits. */ 

if (currentuser) 

{ 

printf ( "serial control allocated by %s\n", currentuser); /* Give up. */ 
FreeMiscResource (MR_SERIALPORT) ; 

} 

else 

{ /* Got them both. */ 

printf ( "serial hardware allocated\n" ) ; 

if ( (signr = AllocSignal ( -1) ) != -1) /* Allocate a signal bit for the */ 
{ /* interrupt handler to signal us. */ 

if (rbfint = AllocMem (sizeof (struct Interrupt), MEMF_PUBLIC | MEMF_CLEAR) ) 

{ 

if (rbfdata = AllocMem (sizeof (struct RBFData) , MEMF_PUBLIC | MEMF_CLEAR) ) 

{ 

rbfdata- >rd_Task = FindTask (NULL) ; /* Init rfbdata structure. */ 
rbf data- >rd_Signal = 1L << signr; 

rbfint ->is_Node . ln_Type = NT_INTERRUPT ; /* Init interrupt node. */ 

strcpy (rbf data- >rd_Name, allocname) ; 

rbf int->is_Node . ln_Name = rbf data- >rd_Name; 

rbf int->is_Data = (APTR) rbf data ; 

rbf int->is_Code = RBFHandler; 

/* Save state of RBF and */ 
priorenable = custom. intenar & INTF_RBF ? TRUE : FALSE; /* interrupt */ 
custom. intena = INTF_RBF; /* disable it. */ 

priorint = Set Int Vector (INTB_RBF, rbfint); 

if (priorint) printf ( "replaced the %s RBF interrupt handler\n", 

priorint ->is_Node . ln_Name) ; 
printf ( "enabling RBF interrupt\n" ) ; 
custom. intena = INTF_SETCLR | INTF_RBF; 

printf ( "waiting for buffer to fill up. Use CTRL-C to break\n"); 
signal = WaitflL << signr | SIGBREAKF_CTRL_C) ; 

if (signal & SIGBREAKF_CTRL_C) printf (" >break<\n" ) ; 
printf ( "Character buffer contains : \n%s\n" , rbf data- >rd_CharBuf f er ) ; 

custom. intena = INTF_RBF; /* Restore previous handler. */ 

SetlntVector (INTB_RBF, priorint) ; 

/* Enable it if it was enabled */ 
if (priorenable) 

custom. intena = INTF_SETCLR| INTF_RBF; /* before. */ 

FreeMem( rbfdata, sizeof (struct RBFData)); 

} 

else printf ( "can' t allocate memory for rbf data\n"); 
FreeMem (rbf int , sizeof (struct Interrupt)); 

} 

else printf ( "can' t allocate memory for interrupt structured") ; 

FreeSignal (signr) ; 

} 

else printf ( "can' t allocate signal\n"); 

FreeMiscResource (MR SERIALBITS) ; /* release serial hardware */ 



FreeMiscResource (MR SERIALPORT) ; 



} 



} /* There is no ' CloseResource ( ) ' function */ 



The assembler interrupt handler code, RBFHandler, reads the complete word of serial input data from the serial 
hardware and then separates the character and flag bytes into separate buffers. When the buffers are full, the 
handler signals the main process causing main to print the character buffer contents, remove the handler, and 
exit. 
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NOTE. The data structure containing the signal to use, task address pointer, and buffers is 
allocated and initialized in main(), and passed to the handler via the is_Data pointer of the 
Interrupt structure. 

* rbf handler .asm. Example interrupt handler for rbf . 

* Assembled with Howesoft Adapt 680x0 Macro Assembler Rel . 1.0 

* hx68 from: rbf handler .asm to rbfhandler.o INCDIR include: 

* blink from lib:c.o rbf.o rbfhandler.o to rbf lib lib :1c. lib lib:amiga. lib 

INCLUDE "exec/types . i" 
INCLUDE "hardware/custom. i" 
INCLUDE "hardware/intbits.i" 

XDEF _RBFHandler 

JSRLIB MACRO 

XREF _LVO\l 
JSR _LVO\l(A6) 
ENDM 

BUFLEN EQU 256 

STRUCTURE RBFDATA, 
APTR rd_task 
ULONG rd_signal 
UWORD rd_buf fercount 
STRUCT rd_charbuffer,BUFLEN+2 
STRUCT rd_flagbuffer,BUFLEN+2 
STRUCT rd_name,3 2 
LABEL RBFDATA_SIZEOF 

* Entered with: 

* DO == scratch 

* Dl == INTENAT & INTREQR (scratch) 

* A0 == custom chips (scratch) 

* Al == is_Data which is RBFDATA structure (scratch) 

* A5 == vector to our code (scratch) 

* A6 == pointer to ExecBase (scratch) 

* Note - This simple handler just receives one buffer full of serial 

* input data, signals main, then ignores all subsequent serial data. 

section code 



RBFHandler: 




MOVE . W 


serdatr (A0) ,D1 


MOVE . W 


rd buf fercount (Al) , DO 


CMPI.W 


#BUFLEN,D0 


BEQ.S 


ExitHandler 


LEA.L 


rd charbuf fer (Al) ,A5 


MOVE . B 


Dl, (A5,D0.W) 


LEA.L 


rd flagbuf fer (Al) ,A5 


LSR.W 


#8,dl 


MOVE . B 


Dl, (A5,D0.W) 



; entry to our interrupt handler 

;get the input word (flags and char) 

get our buffer index 

no more room in our buffer ? 

yes - just exit (ignore new char) 

else get our character buffer address 

store character in our character buffer 

get our flag buffer address 

shift flags down 

store flags in flagbuffer 



ADDQ . W 


#1,D0 


MOVE . W 


D0,rd buf fercount (Al) 


CMPI.W 


#BUFLEN,D0 


BNE.S 


ExitHandler 


MOVE . L 


AO, - (SP) 


MOVE . L 


rd signal (Al) ,D0 


MOVE . L 


rd task(Al) ,A1 


JSRLIB 


Signal 


MOVE . L 


(SP) +,A0 


ExitHandler : 




MOVE . W 


#INTF_RBF,intreq(AO) 


RTS 





increment our buffer index 

and replace it 
did our buffer just become full ? 
no - we can exit 
yes - save custom 
get signal allocated in main ( ) 
and pointer to main task 
tell main we are full 
restore custom 
Note: system call trashed D0-D1/A0-A1 

; clear the interrupt 
; return to exec 
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Interrupt Servers 



As mentioned above, an interrupt server is one of possibly many system interrupt routines that are invoked as the 
result of a single 4703 interrupt. Interrupt servers provide an essential mechanism for interrupt sharing. 

Interrupt servers must be used for PORTS, COPER, VERTB, EXTER, or NMI interrupts. For these interrupts, all 
servers are linked together in a chain. Every server in the chain will be called in turn as long as the previous 
server returned with the processor's Z (zero) flag set. If you determine that an interrupt was specifically for your 
server, you should return with the processor's Z flag cleared (non-zero condition) so that the remaining servers on 
the chain will be skipped. 

Use The Z Flag. VERTB (vertical blank) servers should always return with the Z (zero) flag 
set. The processor Z flag is used rather than the normal function convention of returning a 
result in DO because it may be tested more quickly by Exec upon the server's return. 

The easiest way to set the condition code register is to do an immediate move to the DO register as follows: 

SetZf lag_Calls_Next : 

MOVEQ #0,D0 
RTS 



ClrZf lag_Ends_Chain : 

MOVEQ #1,D0 
RTS 

The same Exec Interrupt structure used for handlers is also used for servers, 
servers must terminate their code with an rts instruction. 



Also, like interrupt handlers, 



Interrupt servers are called in priority order. The priority of a server is specified in its is_Node.ln_Pri field. 
Higher-priority servers are called earlier than lower-priority servers. Adding and removing interrupt servers from 
a particular chain is accomplished with the Exec AddlntServer() and RemlntServer() functions. These functions 
require you to specify both the 4703 interrupt number and a properly initialized Interrupt structure. 

Servers have different register values passed than handlers do. A server cannot count on the DO, D1 , AO, or A6 
registers containing any useful information. However, the highest priority system vertical blank server currently 
expects to receive a pointer to the custom chips AO. Therefore, if you install a vertical blank server at priority 10 
or greater, you must place custom ($DFF000) in AO before exiting. Other than that, a server is free to use D0-D1 
and A0-A1/A5-A6 as scratch. 

Interrupt Server Register Usage 

DO Scratch. 

D1 Scratch. 

AO Scratch except in certain cases (see note above). 



A1 Points to the data area specified by the is_Data field of the Interrupt structure. Because this pointer is 

always fetched (regardless of whether you use it), it is to your advantage to make some use of it 
(scratch). 
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A5 Points to your interrupt code (scratch). 

A6 Scratch. 

In a server chain, the interrupt is cleared automatically by the system. Having a server clear its interrupt is not 
recommended and not necessary (clearing could cause the loss of an interrupt on PORTS or EXTER). 

Here is an example of a program to install and remove a low-priority vertical blank interrupt server: 

;/* vertb.c - Execute me to compile me with SAS C 5.10 

LC -dO -bl -cfistq -v -y - j 73 vertb.c 

Blink FROM LIB : c . o, vertb . o, vertbserver . o TO vertb LIBRARY LIB : LC . lib, LIB : Amiga . lib 

quit ; */ 

/* vertb.c - Vertical blank interrupt server example. Must be linked with vertbserver .o. */ 

#include <exec/memory . h> 
#include <exec/interrupts . h> 
#include <dos/dos.h> 
#include <hardware/custom.h> 
#include <hardware/intbits . h> 
#include <clib/exec_protos . h> 
#include <stdio.h> 

#ifdef LATTICE 

int CXBRK(void) { return(O); } /* Disable Lattice CTRL/C handling */ 

void chkabort (void) { return; } /* really */ 

#endif 

extern void VertBServer ( ) ; /* proto for asm interrupt server */ 

void main (void) 

{ 

struct Interrupt *vbint; 
ULONG counter = ; 
ULONG endcount; 

/* Allocate memory for */ 
if (vbint = AllocMem(sizeof (struct Interrupt), MEMF_PUBLIC | MEMF_CLEAR) ) /*interrupt node. */ 

{ 

vbint ->is_Node.ln_Type = NT_INTERRUPT ; /* Initialize the node. */ 

vbint - >is_Node . ln_Pri = -60; 

vbint - >is_Node . ln_Name = "VertB-Example" ; 

vbint->is_Data = (APTR) Scounter ; 

vbint ->is_Code = VertBServer; 

AddlntServer (INTBJVERTB, vbint); /* Kick this interrupt server to life. */ 

printf ( "VBlank server will increment a counter every frame.\n"); 
printf ( "counter started at zero, CTRL-C to remove server\n"); 

Wait (SIGBREAKF_CTRL_C) ; 

endcount = counter; 

printf ("%ld vertical blanks occurred\nRemoving server\n", endcount); 

RemlntServer (INTBJVERTB, vbint) ; 

FreeMem (vbint , sizeof (struct Interrupt)); 

} 

else printf ( "Can' t allocate memory for interrupt node\n"); 

} 
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* vertbserver .asm. Example simple interrupt server for vertical blank 

* Assembled with Howesoft Adapt 680x0 Macro Assembler Rel . 1.0 

* hx68 from: vertbserver .asm to vertbserver .o INCDIR include: 

* blink from lib:c.o vertb.o vertbserver .o to vertb lib lib :1c. lib lib:amiga. lib 

INCLUDE "exec/types . i" 
INCLUDE "hardware/custom. i" 
INCLUDE "hardware/intbits.i" 



XDEF 



VertBServer 



* Entered with: 

* DO == scratch 

* Dl == scratch 



A0 == scratch (execpt for highest pri vertb server) 

Al == is_Data 

A5 == vector to interrupt code (scratch) 

A6 == scratch 



section code 

JVertBServer : 

ADDI.L #1, (al) 
MOVEQ.L #0,d0 
RTS 
END 



increments counter is_Data points to 
set Z flag to continue to process other vb-servers 
return to exec 



Software Interrupts 



Exec provides a means of generating software interrupts. Software interrupts execute at a priority higher than that 
of tasks but lower than that of hardware interrupts, so they are often used to defer hardware interrupt processing 
to a lower priority. Software interrupts use the same Interrupt data structure as hardware interrupts. As 
described above, this structure contains pointers to both interrupt code and data, and should be initialized as node 
type NTJNTERRUPT (not NT_SOFTINT which is an internal Exec flag). 

A software interrupt is usually activated with the Cause() function. If this function is called from a task, the task 
will be interrupted and the software interrupt will occur. If it is called from a hardware interrupt, the software 
interrupt will not be processed until the system exits from its last hardware interrupt. If a software interrupt occurs 
from within another software interrupt, it is not processed until the current one is completed. However, individual 
software interrupts do not nest, and will not be caused if already running as a software interrupt. 

Don't Trash A6! Software interrupts execute in an environment almost identical to that of 
hardware interrupts, and the same restrictions on allowable system function calls (as 
described earlier) apply to both. Note however that, unlike other interrupts, software interrupts 
must preserve A6. 

Software interrupts are prioritized. Unlike interrupt servers, software interrupts have only five allowable priority 
levels: -32, -16, 0, +16, and +32. The priority should be put into the ln_Pri field prior to calling Cause(). 

Software interrupts can also be generated by message arrival at a PA_SOFTINT message port. The applications 
of this technique are limited since it is not permissible, with most devices, to send IO requests from within interrupt 
code. However, the timer.device does allow such interactions, so a self-perpetuating PA_SOFTINT timer port can 
provide an application with quite consistent timing under varying multitasking loads. The following example 
demonstrates use of a software interrupt and a PA_SOFTINT port. See the "Exec Messages and Ports" chapter 
for more information about messages and ports. 
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;/* timersof tint . c - Execute me to compile me with SAS C 5.10 

LC -bl -do -cfistq -v -y - j 73 timersof tint . c 

Blink FROM LIB : c . o, timersof tint . o TO timersoftint LIBRARY LIB : LC . lib, LIB : Amiga . lib 

quit ; */ 

/* timersof tint . c - Timer device software interrupt message port example. */ 

#include <exec/memory . h> 
#include <exec/interrupts . h> 
#include <devices/timer . h> 
#include <dos/dos.h> 
#include <clib/exec_protos . h> 



#include <clib/dos_protos . h> 
#include <clib/alib_protos . h> 
#include <stdio.h> 

#ifdef LATTICE 

int CXBRK(void) { return(O); } /* Disable Lattice CTRL/C handling */ 

void chkabort (void) { return; } /* really */ 

#endif 

#define MICRO_DELAY 1000 
#define OFF 
#define ON 1 
#define STOPPED 2 

struct TSIData { 

ULONG tsi_Counter; 

ULONG tsi_Flag; 

struct MsgPort *tsi_Port; 

} ; 

struct TSIData *tsidata; 

void tsof tcode (void) ; /* Prototype for our software interrupt code */ 

void main (void) 

{ 

struct MsgPort *port; 
struct Interrupt *softint; 
struct timerequest *tr; 

ULONG endcount ; 

I* Allocate message port, data & interrupt structures. Don't use CreatePortO */ 

/* or CreateMsgPort ( ) since they allocate a signal (don't need that) for a */ 

/* PA_SIGNAL type port. We need PA_SOFTINT. */ 
if (tsidata = AllocMem (sizeof (struct TSIData), MEMF_PUBLIC | MEMF_CLEAR) ) 

{ 

if (port = AllocMem (sizeof (struct MsgPort), MEMF_PUBLIC | MEMF_CLEAR) ) 

{ 

NewList (& (port->mp_MsgList) ) ; /* Initialize message list */ 

if (softint = AllocMem (sizeof (struct Interrupt), MEMF_PUBLIC | MEMF_CLEAR) ) 

{ 

/* Set up the (software) interrupt structure. Note that this task runs at */ 

/* priority 0. Software interrupts may only be priority -32, -16, 0, +16, */ 

/* +32. Also not that the correct node type for a software interrupt is */ 

/* NT_INTERRUPT . (NT_SOFTINT is an internal Exec flag) . This is the same */ 

/* setup as that for a software interrupt which you Cause () . If our */ 

/* interrupt code was in assembler, you could initialize is_Data here to */ 

/* contain a pointer to shared data structures. An assembler software */ 

/* interrupt routine would receive the is_Data in Al . */ 

sof tint- >is_Code = tsoftcode; /* The software interrupt routine */ 
sof tint->is_Data = tsidata; 
sof tint->is_Node . ln_Pri = 0; 

port - >mp_Node . ln_Type = NT_MSGPORT; /* Set up the PA_SOFTINT message port */ 
port->mp_Flags = PA_SOFTINT; /* (no need to make this port public) . */ 

port->mp_SigTask = (struct Task *) softint; /*pointer to interrupt structure */ 

/* Allocate timerequest */ 

if (tr = (struct timerequest *) CreateExtIO (port , sizeof (struct timerequest))) 

{ 

/* Open timer .device . NULL is success. */ 
if (! (OpenDevice ( "timer .device" , UNIT_MICROHZ, (struct IORequest *)tr, 0) ) ) 

{ 

tsidata->tsi_Flag = ON; /* Init data structure to share globally. */ 
tsidata->tsi_Port = port ; 

/* Send of the first timerequest to start. IMPORTANT: Do NOT */ 

/* BeginlOO to any device other than audio or timer from */ 

/* within a software or hardware interrupt. The BeginlOO code */ 

/* may allocate memory, wait or perform other functions which */ 



/* are illegal or dangerous during interrupts. */ 

printf ("starting softint. CTRL-C to break. .. \n" ) ; 

tr->tr_node. io_Command = TR_ADDREQUEST; /*Initial iorequest to start */ 
tr->tr_time. tv_micro = MICRO_DELAY; /* software interrupt. */ 
BeginIO ( (struct IORequest *)tr); 

Wait (SIGBREAKF_CTRL_C) ; 

endcount = tsidata->tsi_Counter ; 

printf ( "timer softint counted %ld milliseconds . \n" , endcount); 

printf ( "Stopping timer . . . \n" ) ; 
tsidata->tsi_Flag = OFF; 

while (tsidata->tsi_Flag != STOPPED) Delay (10); 

CloseDevice ( (struct IORequest *)tr); 

} 

else printf ( "couldn' t open timer .device\n" ) ; 
DeleteExtlO(tr) ; 

} 

else printf ( "couldn' t create timerequest\n" ) ; 

FreeMem (softint , sizeof (struct Interrupt)); 

} 

FreeMem (port , sizeof (struct MsgPort) ) ; 

} 

FreeMem (tsidata, sizeof (struct TSIData) ) ; 



void tsof tcode (void) 

{ 

struct timerequest *tr; 

/* Remove the message from the port. */ 

tr = (struct timerequest *) GetMsg (tsidata->tsi_Port) ; 

/* Keep on going if main() hasn't set flag to OFF. */ 
if ( (tr) && (tsidata->tsi_Flag == ON)) 

{ 

/* increment counter and re-send timerequest--IMPORTANT: This */ 

/* self -perpetuating technique of calling BeginIO ( ) during a software */ 

/* interrupt may only be used with the audio and timer device. */ 

tsidata->tsi_Counter++ ; 

tr->tr_node. io_Command = TR_ADDREQUEST; 

tr->tr_time. tv_micro = MICRO_DELAY; 

BeginIO ( (struct IORequest *)tr); 

} 

/* Tell main() we're out of here. */ 
else tsidata->tsi_Flag = STOPPED; 
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Disabling Interrupts 



As mentioned in the "Exec Tasks" chapter, it is sometimes necessary to disable interrupts when examining or 
modifying certain shared system data structures. However, for proper system operation, interrupts should never 
be disabled unless absolutely necessary, and never for more than 250 microseconds. Interrupt disabling is 
controlled with the Disable() and EnableQ functions. Although assembler DISABLE and ENABLE macros are 
provided, we strongly suggest that you use the system functions rather than the macros for upwards compatibility 
and smaller code size. 

In some system code, there are nested disabled sections. Such code requires that interrupts be disabled with the 
first Disable() and not re-enabled until the last EnableQ. The system Enable() and DisableQ functions are 
designed to permit this sort of nesting. 

DisableQ increments a counter to track how many levels of disable have been issued. Only 126 levels of nesting 



are permitted. Enable() decrements the counter, and reenables interrupts when the last disable level has been 
exited. 



Function Reference 



The following chart gives a brief description of the Exec functions that control interrupts. See the Amiga ROM 
Kernel Reference Manual: Includes and Autodocs for details about each call. 

Table 26-2: Exec Interrupt Functions 



Interrupt Function 


Description 


Addlntserver() 


Add an interrupt server to a system server chain. 


Cause() 


Cause a software interrupt. 


Disable() 


Disable interrupt processing. 


Enable() 


Restart system interrupt processing. 


RemlntServer() 


Remove an interrupt server from a system server chain. 


SetlntVector() 


Set a new handler for a system interrupt vector. 



Chapter 27 
Graphics Primitives 

This chapter describes the basic graphics functions available to Amiga programmers. It covers the graphics 
support structures, display routines and drawing routines. Many of the operations described in this section are 
also performed by the Intuition software. See the Intuition chapters for more information. 

The Amiga supports several basic types of graphics routines: display routines, drawing routines, sprites and 
animation. These routines are very versatile and allow you to define any combination of drawing and display 
areas you may wish to use. 

The first section of this chapter defines the display routines. These routines show you how to form and 
manipulate a display, including the following aspects of display use: 

How to query the graphics system to find out what type of video monitor is attached and which graphics 
modes can be displayed on it. 

How to identify the memory area that you wish to have displayed. 

How to position the display area window to show only a certain portion of a larger drawing area. 

How to split the screen into as many vertically stacked slices as you wish. 

How to determine which horizontal and vertical resolution modes to use. 

How to determine the current correct number of pixels across and lines down for a particular section of 
the display. 

How to specify how many color choices per pixel are to be available in a specific section of the display. 
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The later sections of the chapter explain all of the available modes of drawing supported by the system software, 
including how to do the following: 

Reserve memory space for use by the drawing routines. 

Define the colors that can be drawn into a drawing area. 

Define the colors of the drawing pens (foreground pen, background pen for patterns, and outline pen for 
area-fill outlines). 

Define the pen position in the drawing area. 

Drawing primitives; lines, rectangles, circles and ellipses. 

Define vertex points for area-filling, and specify the area-fill color and pattern. 

Define a pattern for patterned line drawing. 

Change drawing modes. 

Read or write individual pixels in a drawing area. 

Copy rectangular blocks of drawing area data from one drawing area to another. 

Use a template (predefined shape) to draw an object into a drawing area. 



Components of a Display 

In producing a display, you are concerned with two primary components: sprites and the playfield. Sprites are the 
easily movable parts of the display. The playfield is the static part of the display and forms a backdrop against 
which the sprites can move and with which the sprites can interact. 

This chapter covers the creation of the background. Sprites are described in the "Graphics Sprites, Bobs and 
Animation" chapter. 

Introduction to Raster Displays 

There are three major television standards in common use around the world: NTSC, PAL, and SECAM. NTSC is 
used primarily in the United States and Japan; PAL and SECAM are used primarily in Europe. The Amiga 
currently supports both NTSC and PAL. The major differences between the two systems are refresh frequency 
and the number of scan lines produced. Where necessary, the differences will be described and any special 
considerations will be mentioned. 

The Amiga produces its video displays on standard television or video monitors by using raster display 
techniques. The picture you see on the video display screen is made up of a series of horizontal video lines 
stacked one on top of another, as illustrated in the following figure. Each line represents one sweep of an 
electronic video beam, which "paints" the picture as it moves along. The beam sweeps from left to right, 
producing the full screen one line at a time. After producing the full screen, the beam returns to the top of the 
display screen. 
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Figure 27-1 : How the Video Display Picture Is Produced 

The diagonal lines in the figure show how the video beam returns to the start of each horizontal line. 



Effect of Display Overscan on the Viewing Area 

To assure that the picture entirely fills the monitor (or television) screen, the manufacturer of the video display 
device usually creates a deliberate overscan. That is, the video beam is swept across an area that is larger than 
the viewable region of the monitor. 

The video beam actually covers 262 vertical lines (312 for PAL). The user, however, sees only the portion of the 
picture that is within the center region of the display, typically surrounded by a border as illustrated in the figure 
below. The center region is nominally about 200 lines high on an NTSC machine (256 lines for PAL). Overscan 
also limits the amount of video data that can appear on each display line. The width of the center region is 
nominally, about 320 pixels for both PAL and NTSC. 




Vertical 
Blanking 
Interval 



Generally Graphics are 
not displayed in this area. 

Contains approximately 
200 video lines (250 PAL) 
and 320 pixels across 



Figure 27-2: Display Overscan 

Restricts Usable Picture Area 

The flexibility of the Amiga graphics subsystem allows the overscan region, which normally forms the border of 
the display, to be used for application graphics instead. So the nominal dimensions given above can be enlarged. 
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The time during which the video beam is below the bottom line of the viewable region and above the first line is 
called the vertical blanking interval. The recommended minimum to allow for this interval is 21 lines for NTSC (29 
lines for PAL). So, for applications that take full advantage of the overscan area, a maximum of 241 usable lines 
in NTSC (283 in PAL) can be achieved. The display resolution can also be changed by changing the Amiga 
display mode as discussed in the sections below. 

Color Information for the Video Lines 

The hardware reads the system display memory to obtain the color information for each line. As the video display 
beam sweeps across the screen producing the display line, it changes color, producing the images you have 
defined. On the current generation of Amiga hardware, there are 4,096 possible colors. 

Interlace and Non-lnterlace Modes 



In producing the complete display (262 lines in NTSC, 312 in PAL), the video display device produces the top line, 
then the next lower line, then the next, until it reaches the bottom of the screen. When it reaches the bottom, it 
returns to the top to start a new scan of the screen. Each complete set of lines is called a display field. It takes 
about 1/60th of a second to produce a complete NTSC display field (1/50th of a second for PAL). 

The Amiga has two vertical display modes: interlaced and non-interlaced. In non-interlaced mode, the video 
display produces the same picture for each successive display field. A non-interlaced NTSC display normally has 
about 200 lines in the viewable area (up to a maximum of 241 lines with overscan) while a PAL display will 
normally show 256 lines (up to a maximum of 283 with overscan). 

With interlaced mode, the amount of information in the viewable area can be doubled. On an NTSC display this 
amounts to 400 lines (482 with overscan), while on a PAL display it amounts to 512 lines (566 with overscan). 

For interlaced mode, the video beam scans the screen at the same rate (1/60th of a second per complete NTSC 
video display field); however, it takes two display fields to form a complete video display picture and twice as 
much display memory to store line data. During the first of each pair of display fields, the system hardware shows 
the odd-numbered lines of an interlaced display (1 , 3, 5, and so on). During the second display field, it shows the 
even-numbered lines (2, 4, 6 and so on). The second field is positioned slightly lower so that the lines in the 
second field are "interlaced" with those of the first field, giving the higher vertical resolution of this mode. 



Data as Displayed 
| 

| Odd field - Line 1 
| Even field - Line 1 
J Odd field - Line 2 
Even field - Line 2 

I 

| Odd field - Line 200 

J Even field - Line 200 



Data In Memory 

Line 1 
Line 2 
Line 3 
Line 4 



Line 3 99 
Line 400 



Figure 27-3: Interlaced Mode -- Display Fields and Data in Memory 
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The following figure shows a display formed as display lines 1 , 2, 3, 4, . 
uses the same physical display area as a 200-line non-interlaced display. 



400. The 400-line interlaced display 
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Same physical space as used 
by a 200- line (256 PAL), 
noninterlaced display. 












Figure 27-4: Interlaced 



Mode Doubles Vertical Resolution 



During an interlaced display, it appears that both display fields are present on the screen at the same time and 
form one complete picture. However, interlaced displays will appear to flicker if adjacent (odd and even) scan 
lines have contrasting brightness. Choosing appropriate colors for your display will reduce this flicker 
considerably. This phenomenon can also be reduced by using a long-persistence monitor, or alleviated 
completely with a hardware de-interlacer. 

Low, High and Super-High Resolution Modes 



The Amiga also has three horizontal display modes: 
super-high-resolution (SuperHires). 



low-resolution (or Lores), high-resolution (Hires) and 



Normally, these three horizontal display modes have a width of 320 for Lores, 640 for Hires or 1280 for 
SuperHires on both PAL and NTSC machines. However, by taking full advantage of the overscan region, it is 
possible to create dispays up to 362 pixels wide in Lores mode, 724 pixels wide in Hires or 1448 pixels wide in 
SuperHires. Usually, however, you should use the standard values (320, 640 or 1280) for most applications. 

In general, the number of colors available in each display mode decreases as the resolution increases. The 
Amiga has two special display modes that can be used to increase the number of colors available. HAM is 
Hold-And-Modify mode, EHB is Extra-Half-Brite mode. 

Hold-And-Modify (HAM) allows you to display the entire palette of 4,096 colors on-screen at once with certain 
restrictions, explained later. 

Extra-Half-Brite allows for 64 colors on-screen at once; 32 colors plus 32 additional colors that are half the 
intensity of the first 32. For example, if color 1 is defined as OxFFF (white), then color 33 is 0x777 (grey). 
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Display Modes, Colors, and Requirements 

The following chart lists all of the display modes that are available under Release 2 of the Amiga operating 
system, as well as those available under previous releases of the OS. 

15 kHz Amiga 
Display Modes 



Lores 

Lores -Interlaced 

Hires 

Hires -Interlaced 

SuperHires* 



SuperHires -Interlaced* 



Default 


Resolution 


Maximum 


Supports 


NTSC 


PAL 


Colors 


HAM /EHB 


320x200 


320x256 


32 of 4096 


Yes 


320x400 


320x512 


32 of 4096 


Yes 


640x200 


640x256 


16 of 4096 


No 


640x400 


640x512 


16 of 4096 


No 


1280x200 


1280x256 


4 out of 64 


No 


1280x400 


1280x512 


4 out of 64 


No 



*Requires both Release 2 and ECS . 



31 kHz Amiga 


Default 




Maximum 


Supports 


Display Modes* 


Resolution 


32 


Colors 

out of 4096 


HAM/EHB 


VGA-ExtraLores 


160x480 


Yes 


VGA- Ext raLores- Inter lace 


160x960 


32 


out of 4096 


Yes 


VGA- Lores 


3 2 0x480 


16 


out of 4096 


No 


VGA- Lores -Interlace 


320x960 


16 


out of 4096 


No 


Productivity 


640x480 


4 < 


out of 64 


No 


Productivity- Interlace 


640x960 


4 < 


out of 64 


No 



*31 kHz modes require Release 2, ECS and either a bi-scan or 
multi-scan monitor. 



A2024* 
Display Modes 

A2024-10HZ 
A2024-15HZ 



Default Resolution 
NTSC PAL 



1008x800 
1008x800 



1008x1024 
1008x1024 



Maximum 
Colors 

4 out of 4 grey levels 
4 out of 4 grey levels 



*A2 024 modes require special hardware and either Release 2 or 
special software available from the monitor's manufacturer. 

About ECS 



ECS stands for Enhanced Chip Set, the latest version of the Amiga's custom chips that provides for improved 
graphics capabilities. Some of the special features of the Amiga's graphics sub-system such as the VGA, 
Productivity and SuperHires display modes require the ECS. 

SuperHires (35 nanosecond) Pixel Resolutions 

The enhanced version of the Denise chip can generate SuperHires pixels that are twice as fine as Hires pixels. It 
is convenient to refer to pixels here by their speed, rather than width, for reasons that will be explained below. 
They are approximately 35nS long, while Hires are 70nS, and Lores 140nS. In the absence of any other features, 
this can bring a new mode with nominal dimensions of 1280 x 200 (NTSC) or 1280 x 256 (PAL). This mode 
requires the ECS Agnus chip as well. 
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When Denise is generating these new fast pixels, simple bandwidth arithmetic indicates that at most two bitplanes 
can be supported. Also note that with two bitplanes, DMA bandwidth is saturated. The palette for SuperHires 
pixels is also restricted to 64 colors. 

Productivity Mode 

The enhanced version of the Denise chip can support monitor horizontal scan frequencies of 31 KHz, twice the old 
15.75KHz rate. This provides over 400 non-interlaced horizontal lines in a frame, but requires the use of a 
multiple scan rate, or multi-sync monitor. 

This effect speeds up the video beam roughly by a factor of two, which has the side effect of doubling the width of 
a pixel emitted at a given speed. Thus, for a given Denise mode, pixels are twice as fat, and there are half as 
many on a given line. 

The increased scan rate interacts with all of the Denise modes. So with both SuperHires (35nS) pixels and the 
double scan rate the display generated would be 640 pixels wide by more than 400 rows, non-interlaced, with up 
to four colors from a palette of 64. This combination is termed Productivity mode, and the default international 
height is 480 rows. This conforms, in a general way, to the VGA Mode 3 Standard 851 4/A. 

The support in Agnus is actually more flexible, and gives the ability to conform to special-purpose modes, such as 
displays synchronized to motion picture cameras. 



Selectable PAL/NTSC 

The Enhanced Chip Set can be set to NTSC or PAL modes under software control. Its initial default behavior is 
determined by a jumper or trace on the system motherboard. This has no bearing on Productivity mode and other 
programmable scan operations, but the new system software can support displays in either mode. 

Determining Chip Version 

It is possible to ascertain whether the ECS chips are in the machine at run time by looking in the ChipRevBits() 
field of the GfxBase structure. If this field contains the flag for the chip you are interested in (as defined in the 
<gfxbase.h> include file), then that chip is present. 

For example, if the C statement (GfxBase- >chipRevBitso & gfxf_hr_agnus) evaluates to non-zero, then 
the machine contains the ECS version of the Agnus chip and has advanced features such as the ability to handle 
larger rasters. Older Agnus chips were capable of handling rasters up to 1 ,024 by 1 ,024 pixels. The ECS Agnus 
can handle rasters up to 16,384 by 16,384 pixels. 

If (GfxBase- >ChipRevBitsO & gfxf_hr_denise) is non-zero, then the ECS version of the Denise chip is 
present. Having both the ECS Agnus and ECS Denise present allows for the special SuperHires, VGA and 
Productivity display modes available in Release 2. For more information on ECS and the custom chips, refer to 
the Amiga Hardware Reference Manual. 
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Forming an Image 

To create an image, you write data (that is, you "draw") into a memory area in the computer. From this memory 
area, the system can retrieve the image for display. You tell the system exactly how the memory area is 
organized, so that the display is correctly produced. You use a block of memory words at sequentially increasing 
addresses to represent a rectangular region of data bits. The following figure shows the contents of three 
example memory words: bits are shown as blank rectangles, and 1 bits as filled-in rectangles. 

Contents of three memory words, all adjacent to each other. Note that N is expressed as a 
byte-address . 



LLLLLLLI#I#LLLLLLLI 

Memory Location N (0x0180) 

LLLLLI#I#I#I#I#I#LLLLLI 

Memory Location N+2 (0x07E0) 

LLLLLLLI#I#LLLLLLLI 

Memory Location N+4 (0x0180) 

Figure 27-5: Sample Memory Words 

The system software lets you define linear memory as rectangular regions, called bitplanes. The figure below 
shows how the system would organize three sequential words in memory into a rectangular bitplane with 
dimensions of 16 x 3 pixels. 



; _|#|#| !_:_!_:_!_, Memory Location N 

|#|#|#|##|#LI_LI_I_I Memory Location N+2 



l_l_l_l_l_l_l_l#l#l_l_l_l_l_l_l_l Memory Location N+4 

Figure 27-6: A Rectangular Bitplane Made from 3 Memory Words 

The following figure shows how 4,000 words (8,000 bytes) of memory can be organized to provide enough bits to 
define a single bitplane of a full-screen, low-resolution video display (320 x 200). 



Line l b »»»»»» j 

Memory Location N Memory Location N+38 

Lines b »»»»»» j 

Memory Location N+40 Memory Location N+78 

Last Line I I I I'TTTI I b »» m » « 

Memory Location N+7960 Memory Location N+7998 

Figure 27-7: Bitplane for a Full-screen, Low-resolution Display 
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Each memory data word contains 16 data bits. The color of each pixel on a video display line is directly related to 
the value of one or more data bits in memory, as follows: 

If you create a display in which each pixel is related to only one data bit, you can select from only two 
possible colors, because each bit can have a value of only or 1 . 

If you use two bits per pixel, there is a choice of four different colors because there are four possible 
combinations of the values of and 1 from each of the two bits. 

If you specify three, four, or five bits per pixel, you will have eight, sixteen, or thirty-two possible choices 
of a color for a pixel. 

If you use six bits per pixel, then depending on the video mode (EHB or HAM), you will have sixty-four or 
4,096 possible choices for a pixel. 

To create multicolored images, you must tell the system how many bits are to be used per pixel. The number of 
bits per pixel is the same as the number ofbitplanes used to define the image. 

As the video beam sweeps across the screen, the system retrieves one data bit from each bitplane. Each of the 
data bits is taken from a different bitplane, and one or more bitplanes are used to fully define the video display 
screen. For each pixel, data-bits in the same x,y position in each bitplane are combined by the system hardware 
to create a binary value. This value determines the color that appears on the video display for that pixel. 



one pixel 



Btsfrom planes 
5,4,3,2,1 



Color Registers 




Figure 27-8: Bits from Each Bitplane Select Pixel Color 

You will find more information showing how the data bits actually select the color of the displayed pixel in the 
section below called "ViewPort Color Selection." 
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Role of the Copper (Coprocessor) 

The Amiga has a special-purpose coprocessor, called the Copper, that can control nearly the entire graphics 
system. The Copper can control register updates, reposition sprites, change the color palette, and update the 
blitter. The graphics and animation routines use the Copper to set up lists of instructions for handling displays, 
and advanced programmers can create their own custom Copper lists. 

Display Routines and Structures 

CAUTION: This section describes the lowest-level graphics interface to the system hardware. 
If you use any of the routines and the data structures described in these sections, your 
program will essentially take over the entire display. In general, this is not compatible with 
Intuition's multiwindow operating environment since Intuition calls these low-level routines for 
you. 

The descriptions of the display routines, as well as those of the drawing routines, occasionally use the same 
terminology as that in the Intuition chapters. These routines and data structures are the same ones that Intuition 
software uses to produce its displays. 

The computer produces a display from a set of instructions you define. You organize the instructions as a set of 
parameters known as the View structure (see the <graphics/view.h> include file for more information). The 
following figure shows how the system interprets the contents of a View structure. This drawing shows a 
complete display composed of two different component parts, which could (for example) be a low-resolution, 
multicolored part and a high-resolution, two-colored part. 



Video Display 






Viewport* I 



Viewports must be 

seperated by at 

least one blank line 

(sometimes more). 



Viewport #2 



Background color 
shows here 



A complete display is composed 
of one or more "Viewports." 



Figure 27-9: The Display Is Composed of Viewports 
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A complete display consists of one or more Viewports, whose display sections are vertically separated from each 
other by at least one blank scan line (non-interlaced). (If the system must make many changes to the display 
during the transition from one ViewPort to the next, there may be two or more blank scanlines between the 
Viewports.) The viewable area defined by each ViewPort is rectangular. It may be only a portion of the full 
ViewPort, it may be the full ViewPort, or it may be larger than the full ViewPort, allowing it to be moved within 
the limits of its DisplayClip. You are essentially defining a display consisting of a number of stacked rectangular 
areas in which separate sections of graphics rasters can be shown. 

Limitations on the Use of Viewports 



The system software for defining Viewports allows only vertically stacked fields to be defined. The following figure 
shows acceptable and unacceptable display configurations. 



AnnspitahlB 



^J Innnrrent ^^^ 

(Does not use at least one 
blank line between Viewports) 

























I J 









^^f Incnrrert ^^^ 

(Cannot have overlapping 
Viewports) 



Inrnrrent 

(Cannot create multiple 
horizontal Viewports) 



Figure 27-10: Correct and Incorrect Uses of Viewports 

A ViewPort is related to the custom screen option of Intuition. In a custom screen, you can split the screen into 
slices as shown in the "correct" illustration of the above figure. Each custom screen can have its own set of colors, 
use its own resolution, and show its own display area. 
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Characteristics of a Viewport 



To describe a ViewPort fully, you need to set the following parameters: height, width, depth and display mode. 

In addition to these parameters, you must tell the system the location in memory from which the data for the 
ViewPort display should be retrieved (by associating with it a BitMap structure) and how to position the final 
ViewPort display on the screen. The ViewPort will take on the user's default Workbench colors unless otherwise 
instructed with a ColorMap. See the section called "Preparing the ColorMap Structure" for more information. 

Viewport Size Specifications 

The following figure illustrates that the variables DHeight, and DWidth specify the size of a ViewPort. 

DISPLAY BIT-PLANES 



DHeight = how 
many lines tall 



-- DWidth = how -- | 
many pixels wide 

I 



Figure 27-11 : Size Definition for a ViewPort 



ViewPort Height 

The DHeight field of the ViewPort structure determines how many video lines will be reserved to show the height 
of this display segment. The size of the actual segment depends on whether you define a non-interlaced or an 
interlaced display. An interlaced ViewPort displays twice as many lines as does a non-interlaced ViewPort in the 
same physical height. 

For example, a complete View consisting of two Viewports might be defined as follows: 

ViewPort 1 is 150 lines, high-resolution mode (uses the top three-quarters of the display). 

ViewPort 2 is 49 lines of low-resolution mode (uses the bottom quarter of the display and allows the 
space for the required blank line between Viewports). 

Initialize the height directly in DHeight. Nominal height for a non-interlaced display is 200 lines for NTSC, 256 for 
PAL. Nominal height for an interlaced display is 400 lines for NTSC, 512 for PAL. 
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To set your ViewPort to the maximum supported (displayable) height, use the following code fragment (this 
requires Release 2): 

struct Dimensionlnf o querydims; 
struct Rectangle *oscan; 
struct ViewPort viewport; 

if (GetDisplaylnf oData ( NULL, (TJBYTE * ) &querydims , sizeof (struct Dimensionlnf o) , 
DTAG DIMS, modelD )) 



{ 



/* Use StdOScan instead of MaxOScan to get standard */ 
/* overscan dimensions as set by the user in Overscan */ 
/* Preferences */ 

oscan = &querydims .MaxOScan ; 

viewport- >DHeight = oscan- >MaxY - oscan- >MinY + 1; 
} 

ViewPort Width 

The DWidth variable in the ViewPort structure determines how wide, in pixels, the display segment will be. To 
set your ViewPort to the maximum supported (displayable) NTSC high-resolution width, use the following 
fragment (this requires Release 2): 

struct Dimensionlnf o querydims; 
struct Rectangle *oscan; 
struct ViewPort viewport; 

/* Use PAL_MONITOR_ID instead of NTSC_MONITOR_ID to get PAL */ 
/* dimensions */ 

if (GetDisplaylnf oData ( NULL, (UBYTE * ) &querydims , sizeof (querydims) , 
DTAG_DIMS, NTSC_MONITOR_ID|HIRES_KEY )) 

{ 

/* Use StdOScan instead of MaxOScan to get standard */ 

/* overscan dimensions as set by the user in Overscan */ 

/* Preferences */ 

oscan = &querydims .MaxOScan ; 

viewport ->DWidth = oscan- >MaxX - oscan- >MinX + 1; 
} 

You may specify a smaller value of pixels per line to produce a narrower display segment or simply set 
ViewPort.DWidth to the nominal value for this resolution. 

Although the system software allows you define low-resolution displays as wide as 362 pixels and high-resolution 
displays as wide as 724 pixels, you should use caution in exceeding the normal values of 320 or 640, 



respectively. Because display overscan varies from one monitor to another, many video displays will not be able 
to show all of a wider display, and sprite display may also be affected. However, if you use the standard overscan 
values (Dimensionlnfo.StdOScan) provided by the Release 2 function GetDisplaylnfoDataQ as shown above, 
the user's preference for the size of the display will be satisfied. 

If you are using hardware sprites or VSprites with your display, and you specify ViewPort widths exceeding 320 
or 640 pixels (for low or high-resolution, respectively), it is likely that some hardware sprites will not be properly 
rendered on the screen. These sprites may not be rendered because playfield DMA (direct memory access) takes 
precedence over sprite DMA when an extra-wide display is produced. See the Amiga Hardware Reference 
Manual tox a more complete description of this phenomenon. 

ViewPort Color Selection 

The maximum number of colors that a ViewPort can display is determined by the depth of the BitMap that the 
ViewPort displays. The depth is specified when the BitMap is initialized. See the section below called "Preparing 
the BitMap Structure." 
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Depth determines the number of bitplanes used to define the colors of the rectangular image you are trying to 
build (the raster image) and the number of different colors that can be displayed at the same time within a 
ViewPort. For any single pixel, the system can display any one of 4,096 possible colors. 

The following table shows depth values and the corresponding number of possible colors for each value. 

Table 27-1 : Depth Values and Number of Colors in the ViewPort 



Colors 


Depth Val 


.ue 








2 




1 






4 




2 










8 




3 




(Note : 


D 




16 




4 




(Notes 


1, 


,2) 


32 




5 




(Notes 


1, 


.2,3) 


16 




6 




(Notes 


1, 


,4) 


64 




6 




(Notes 


1, 


,2,3,5 


4, 096 




6 




(Notes 


1, 


,2,3,6 


Notes : 














1 . Not avai 


lable 


for 


SUPERHIRES . 







2 . Single-playf ield mode only - DUALPF not one of the 

Viewport's attributes. 

3 . Low-resolution mode only - neither HIRES nor 
SUPERHIRES one of the ViewPort attributes. 

4 . Dual Playfield mode - DUALPF is an attribute of this 
ViewPort. Up to eight colors (in three planes) for 
each playfield. 

5. Extra-Half -Brite mode - EXTRA_HALFBRITE is an 
attribute of this ViewPort. 

6 . Hold-And-Modify mode only - HAM is an attribute of 
this ViewPort. 

The color palette used by a ViewPort is specified in a ColorMap. See the section called "Preparing the 
ColorMap" for more information. 

Depending on whether single- or dual-playfield mode is used, the system will use different color register groupings 
for interpreting the on-screen colors. The table below details how the depth and the different ViewPort modes 
affect the registers the system uses. 



Table 27-2: Color Registers Used in Single-playfield Mode 



Color 
Depth Registers Used 



1 0,1 

2 0-3 

3 0-7 

4 0-15 

5 0-31 

6 0-31 (if EXTRA_HALFBRITE is an 

attribute of this Viewport.) 

6 0-15 (if HAM is an attribute of 

this Viewport . ) 
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The following table shows the five possible combinations when DUALPF is an attribute of the ViewPort. 

Table 27-3: Color Register Used in Dual-playfield Mode 



Depth 




Color 


Depth 


Color 


(PF- 


1) 


Registers 


(PF- 


2) 


Registers 


1 




0, 1 


1 




8, 9 


2 




0-3 


1 




8, 9 


2 




0-3 


2 




8-11 


3 




0-7 


2 




8-11 


3 




0-7 


3 




8-15 



Viewport Display Modes 

The system has many different display modes that you can specify for each ViewPort. Under 1 .3, the eight 
constants that control the modes are DUALPF, PFBA, HIRES, SUPERHIRES, LACE, HAM, SPRITES, and 
EXTRA_HALFBRITE. Some, but not all of the modes can be combined in a ViewPort. HIRES and LACE 
combine to make a high-resolution, interlaced ViewPort, but HIRES and SUPERHIRES conflict, and cannot be 
combined. 

Under 1 .3, you set these flags directly in the Modes field during initialization of the ViewPort. Under Release 2, 
there are many more display modes possible than in 1 .3 so a new system of flags and structures is used to set 
the mode. With Release 2, you set the display mode for a ViewPort by using the VideoControl() function as 
described in the section on "Monitors, Modes and the Display Database" later in this chapter. 

The DUALPF and PFBA modes are related. DUALPF tells the system to treat the raster specified by this 
ViewPort as the first of two independent and separately controllable playfields. It also modifies the manner in 
which the pixel colors are selected for this raster (see the above table). 

When PFBA is specified, it indicates that the second playfield has video priority over the first one. Playfield 
relative priorities can be controlled when the playfield is split into two overlapping regions. Single-playfield and 
dual-playfield modes are discussed below in "Advanced Topics." 

HIRES tells the system that the raster specified by this ViewPort is to be displayed with (nominally) 640 horizontal 
pixels, rather than the 320 horizontal pixels of Lores mode. 

SUPERHIRES tells the system that the raster specified by this ViewPort is to be displayed with (nominally) 1280 
horizontal pixels. This can be used with 31 kHz scan rates to provide the VGA and Productivity modes available 
in Release 2. SUPERHIRES modes require both the ECS and Release 2. See the section on "Determining Chip 
Versions" earlier in this chapter for an explanation of how to find out if the ECS is present. 

LACE tells the system that the raster specified by this ViewPort is to be displayed in interlaced mode. If the 
ViewPort is non-interlaced and the View is interlaced, the ViewPort will be displayed at its specified height and 



will look only slightly different than it would look when displayed in a non-interlaced View (this is handled by the 
system automatically). See "Interlaced Mode vs. Non-interlaced Mode" below for more information. 
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HAM tells the system to use "hold-and-modify" mode, a special mode that lets you display up to 4,096 colors on 
screen at the same time. It is described in the "Advanced Topics" section. 

SPRITES tells the system that you are using sprites in this display (either VSprites or Simple Sprites). The system 
will load color registers for the sprites. Note that since the mouse pointer is a sprite, omitting this mode will 
prevent the mouse pointer from being displayed when this ViewPort is frontmost. See the "Graphics Sprites, 
Bobs and Animation" chapter for more information about sprites. 

EXTRAJHALFBRITE tells the system to use the Extra-Half-Brite mode, a special mode that allows you to display 
up to 64 colors on screen at the same time. It is described in the "Advanced Topics" section. 

If you peruse the <graphics/view.h> include file you will see another flag, EXTENDED_MODE. Never set this flag 
yourself; it is used by the Release 2 system to control more advanced mode features. 

Be sure to read the section on "Monitors, Modes and the Display Database" for additional information about the 
ViewPort mode and how it has changed in the Release 2 version of the operating system. 

Single-playfield Mode vs. Dual-playfield Mode 

When you specify single-playfield mode you are asking that the system treat all bitplanes as part of the definition 
of a single playfield image. Each of the bitplanes defined as part of this ViewPort contributes data bits that 
determine the color of the pixels in a single playfield. 




Figure 27-12: A Single-playfield Display 

If you use dual-playfield mode, you can define two independent, separately controllable playfield areas as shown 
on the next page. 
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Figure 27-13: A Dual-playfield Display 

In the previous figure, PFBA was included in the display mode. If PFBA had not been included, the relative 
priorities would have been reversed; playfield 2 would have appeared to be behind playfield 1 . 

Low-resolution Mode vs High-resolution Mode 

In LORES mode, horizontal lines of 320 pixels fill most of the ordinary viewing area. The system software lets you 
define a screen segment width up to 362 pixels in this mode, or you can define a screen segment as narrow as 
you desire (minimum of 16 pixels). In HIRES mode, 640 pixels fill a horizontal line. In this mode you can specify 
any width from 16 to 724 pixels. In SUPERHIRES mode, 1280 pixels fill a horizontal line. In this mode you can 
specify any width from 16 to 1448 pixels. The fact that many monitor manufacturers set their monitors to overscan 
the video display normally limits you to showing only 16 to 320 pixels per line in LORES, 16 to 640 pixels per line 
in HIRES, or 16 to 1280 pixels per line in SUPERHIRES. Under Release 2, the user can set the monitor's 
viewable screen size with the Preferences Overscan editor. 
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320 Pixels across 
width of 352 possible 



/iewPort.Modes = 



640 Pixels Across 
width of 704 possible 



yiewPortlvlodes = HIRES 




ViewPort.Modes = SUPERHIRES 

Figure 27-14: How HIRES and SUPERHIRES Affect the Width of Pixels 

Interlace Mode vs Non-interlaced Mode 

In interlaced mode, there are twice as many lines available as in non-interlaced mode, providing better vertical 

resolution in the same display area. 



400 lines define 
a full screen 



ViewPort.Modes = 



200 lines define 
a full screen 



ViewPort.Modes=LACE 



Figure 27-15: How LACE Affects Vertical Resolution 

If the View structure does not specify LACE, and the ViewPort specifies LACE, only the top half of the ViewPort 
data will be displayed. If the View structure specifies LACE and the ViewPort is non-interlaced, the same 
ViewPort data will be repeated in both fields. The height of the ViewPort display is the height specified in the 
ViewPort structure. If both the View and the ViewPort are interlaced, the ViewPort will be built with double the 
normal vertical resolution. That means it will need twice as much data space in memory as a non-interlaced 
picture to fill the display. 
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Viewport Display Method 

The picture you create in memory can be larger than the screen image that can be displayed within your 
ViewPort. This big picture (called a raster and represented by the BitMap structure) can have a maximum size 
dependent upon the version of the Agnus chip in the Amiga. The ECS Agnus can handle rasters up to 16,384 by 
1 6,384 pixels. Older Agnus chips are limited to rasters up to 1 ,024 by 1 ,024 pixels. The section earlier in this 
chapter on "Determining Chip Versions" explains how to find out which Agnus is installed. 

The example in the following figure introduces terms that tell the system how to find the display data and how to 
display it in the ViewPort. These terms are RHeight, RWidth, RyOffset, RxOffset, DHeight, DWidth, DyOffset 
and DxOffset. 




Figure 27-16: ViewPort Data Area Parameters 

The terms RHeight and RWidth do not appear in actual system data structures. They refer to the dimensions of 
the raster and are used here to relate the size of the raster to the size of the display area. RHeight is the number 
of rows in the raster and RWidth is the number of bytes per row times 8. The raster shown in the figure is too big 
to fit entirely in the display area, so you tell the system which pixel of the raster should appear in the upper left 
corner of the display segment specified by your ViewPort. The variables that control that placement are 
RyOffset and RxOffset. 

To compute RyOffset and RxOffset, you need RHeight, RWidth, DHeight, and DWidth. The DHeight and 

DWidth variables define the height and width in pixels of the portion of the display that you want to appear in the 
ViewPort. The example shows a full-screen, low-resolution mode (320-pixel), non-interlaced (200-line) display 
formed from the larger overall picture. 
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Normal values for RyOffset and RxOffset are defined by the formulas: 



RyOffset < 
RxOffset < 



(RHeight 
(RWidth - 



- DHeight) 
DWidth) 



Once you have defined the size of the raster and the section of that raster that you wish to display, you need only 
specify where to put this ViewPort on the screen. This is controlled by the ViewPort variables DyOffset and 
DxOffset. These are offsets relative to the View.DxOffset and DyOffset. Possible NTSC values for DyOffset 
range from -23 to +217 (-46 to +434 if the ViewPort is interlaced), PAL values range from -15 to +267 (-30 to 
+534 for interlaced ViewPorts). Possible values for DxOffset range from -18 to +362 (-36 to +724 if the 
ViewPort is Hires, -72 to +1448 if SuperHires), when the View is in its default, initialized position. 

The parameters shown in the figure above are distributed in the following data structures: 

View (information about the whole display) includes the variables that you use to position the whole 
display on the screen. The View structure contains a Modes field used to determine if the whole 
display is to be interlaced or non-interlaced. It also contains pointers to its list of ViewPorts and pointers 



to the Copper instructions produced by the system to create the display you have defined. 

ViewPort (information about this segment of the display) includes the values DxOffset and DyOffset 
that are used to position this portion relative to the overall View. The ViewPort also contains the 
variables DHeight and DWidth, which define the size of this display segment; a Modes variable; and a 
pointer to the local ColorMap. Under Release 2, the VideoControlQ function and its various tags are 
used to manipulate the ColorMap and ViewPort.Modes. Each ViewPort also contains a pointer to the 
next ViewPort. You create a linked list of Viewports to define the complete display. 

Raslnfo (information about the raster) contains the variables RxOffset and RyOffset. It also contains 
pointers to the BitMap structure and to a companion Raslnfo structure if this is a dual playfield. 

BitMap (information about memory usage) tells the system where to find the display and drawing area 
memory and shows how this memory space is organized, including the display's depth. 

You must allocate enough memory for the display you define. The memory you use for the display may be shared 
with the area control structures used for drawing. This allows you to draw into the same areas that you are 
currently displaying on the screen. 

As an alternative, you can define two BitMaps. One of them can be the active structure (that being displayed) 
and the other can be the inactive structure. If you draw into one BitMap while displaying another, the user cannot 
see the drawing taking place. This is called double-buffering of the display. See "Advanced Topics" below for an 
explanation of the steps required for double-buffering. Double-buffering takes twice as much memory as 
single-buffering because two full displays are produced. 

To determine the amount of required memory for each ViewPort for single-buffering, you can use the following 
formula. 

#include <graphics/gfx.h> 

/* Depth, Width, and Height get set to something reasonable. */ 
UBYTE Depth, Width, Height; 

/* Calculate resulting VP size. */ 
bytes_per_ViewPort = Depth * RASSIZE (Width, Height); 
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RASSIZEQ is a system macro attuned to the current design of the system memory allocation for display rasters. 
See the <graphics/gfx.h> include file for the formula with which RASSIZE() is calculated. 

For example, a 32-color ViewPort (depth = 5), 320 pixels wide by 200 lines high currently uses 40,000 bytes. A 
16-color ViewPort (depth = 4), 640 pixels wide by 400 lines high currently uses 128,000 bytes. 

Forming a Basic Display 

Here are the data structures that you need to define to create a basic display: 

struct View view; /* These get used in all versions of */ 

struct ViewPort viewport; /* the OS */ 
struct BitMap bitMap; 
struct Raslnfo raslnfo; 
struct ColorMap *cm; 

struct ViewExtra *vextra; /* Extra View data, new in Release 2 */ 
struct ViewPortExtra *vpextra; /* Extra ViewPort data, new in Release 2 */ 
struct MonitorSpec *monspec ; /* Monitor data needed in Release 2 */ 

struct Dimensionlnf o dimquery; /* Display dimension data needed in Release 2 */ 

ViewExtra and ViewPortExtra are new data structures used in Release 2 to hold extended data about their 
corresponding parent structure. ViewExtra contains information about the video monitor being used to render the 
View. ViewPortExtra contains information required for clipping of the ViewPort. 

GfxNewQ is used to create these extended data structures and GfxAssociateQ is used to associate the 



extended data structure with an appropriate parent structure. Although GfxAssociateQ can associate a 
ViewPortExtra struct u re with a ViewPort, it is better to use VideoControl( ) with the 
VTAG_VIEWPORTEXTRA_SET tag instead. Keep in mind that GfxNew() allocates memory for the resulting data 
structure which must be returned using GfxFree() before the application exits. The function GfxLookUp() will find 
the address of an extended data structure from the address of its parent. 

Preparing the View Structure 

The following code prepares the View structure for further use: 

InitView(&view) ; /* Initialize the View. */ 

view. Modes |= LACE; /* Only interlaced, 1.3 displays require this */ 

For Release 2 applications, a ViewExtra structure must also be created with GfxNewQ and associated with this 
View with GfxAssociateQ as shown in the example programs RGBBoxes.c and WBCIone.c. 

/* Form the ModelD from values in <displayinf o.h> */ 
modeID=DEFAULT_MONITOR_ID | HIRESLACE_KEY; 

/* Make the ViewExtra structure */ 
if( vextra=GfxNew(VIEW_EXTRA_TYPE) ) 

{ 

/* Attach the ViewExtra to the View */ 

GfxAssociate (&view , vextra); 

view. Modes |= EXTENDJVSTRUCT; 

/* Initialize the MonitorSpec field of the ViewExtra */ 
if ( monspec=OpenMonitor (NULL, mode ID) ) 

vextra- >Monitor=monspec ; 
else 

fail ("Could not get MonitorSpec\n" ) ; 

} 
else fail ("Could not get ViewExtra\n" ) ; 
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Preparing the BitMap Structure 

The BitMap structure tells the system where to find the display and drawing memory and how this memory space 
is organized. The following code section prepares a BitMap structure, including allocation of memory for the 
bitmap. This is done with two functions, InitBitMapQ and AllocRaster(). InitBitMapQ takes four arguments-a 
pointer to a BitMap and the depth, width, and height of the desired bitmap. Once the bitmap is initialized, 
memory for its bitplanes must be allocated. AllocRasterQ takes two arguments-width and height. Here is a 
code section to initialize a bitmap: 

/* Init BitMap for Raslnfo. */ 
InitBitMap (&bitMap, DEPTH, WIDTH, HEIGHT); 

/* Set the plane pointers to NULL so the cleanup routine will know */ 
/* if they were used. */ 
for(depth=0; depth<DEPTH; depth++) 
bitMap. Planes [depth] = NULL; 

/* Allocate space for BitMap. */ 
for(depth=0; depth<DEPTH; depth++) 

{ 

bitMap. Planes [depth] = (PLANEPTR) AllocRaster (WIDTH, HEIGHT); 
if (bitMap. Planes [depth] == NULL) 
cleanExit (RETURN WARN) ; 



This code allocates enough memory to handle the display area for as many bitplanes as the depth you have 
defined. 



Preparing the Raslnfo Structure 

The Raslnfo structure provides information to the system about the location of the BitMap as well as the 
positioning of the display area as a window against a larger drawing area. Use the following steps to prepare the 
Raslnfo structure: 

/* Initialize the Raslnfos. */ 
raslnfo. BitMap = ShitMap; /* Attach the corresponding BitMap. */ 
raslnf o.RxOf f set =0; /* Align upper left corners of display */ 
raslnf o.RyOf f set =0; /* with upper left corner of drawing area.*/ 
raslnfo. Next = NULL; /* for a single playfield display, there 

* is only one Raslnfo structure present */ 

The system may be made to reinterpret the RxOffset and RyOffset values in a View/Port's Raslnfo structure by 
calling ScrollVPortQ with the address of the ViewPort. Changing one or both offsets and calling ScrollVPort() 
has the effect of scrolling the ViewPort. 

Preparing the ViewPort Structure 

To prepare the ViewPort structure for further use, you call lnitVPort() and initialize certain fields as follows: 

InitVPort (&viewPort) ; /* Initialize the ViewPort. */ 

viewport .Raslnf o = kraslnfo; /* The raslnfo must also be initialized */ 
viewport .DWidth = WIDTH; viewPort .DHeight = HEIGHT; 

/* Under 1.3, you should set viewport .Modes here to select a display 

* mode. Under Release 2, use VideoControl ( ) with VTAG_NORMAL_DISP_SET 

* to select a display mode by attaching a Displaylnfo structure to 

* the ViewPort. */ 
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The lnitVPort() routine presets certain default values in the ViewPort structure. The defaults include: 

Modes variable set to zero-this means you select a low-resolution display. (To alter this, use 
VideoControl() with the VTAG_NORMAL_DISP_SETtag as explained below.) 

Next variable set to NULL-no other ViewPort is linked to this one. If you want a display with multiple 
Viewports, you must fill in the link yourself. 

If you want to create a View with two or more Viewports you must declare and initialize the Viewports as above. 
Then link them together using the ViewPort. Next field with a NULL link for the ViewPort at the end of the chain: 

viewPortA.Next = &viewPortB; /* Tell 1st one the address of the 2nd. */ 
viewPortB .Next = NULL; /* There are no others after this one. */ 

For Release 2 applications, once a ViewPort has been prepared, a ViewPortExtra structure must also be 
created with GfxNew(), initialized, and associated with the ViewPort via the VideoControl() function. In addition, 
a Displaylnfo for this mode must be attached to the ViewPort. The fragment below shows how to do this. For 
complete examples, refer to the program listings of RGBBoxes.c and WBCIone.c. 

struct Tagltem vcTags [] = /* These tags will be passed to */ 

{ /* the VideoControl ( ) function to */ 

{ VTAG_ATTACH_CM_SET, NULL }, /* set up the extended ViewPort */ 

{ VTAG_VIEWPORTEXTRA_SET, NULL }, /* structures required in Release */ 

{ VTAG_NORMAL_DISP_SET, NULL }, /* 2. The NULL ti_Data field of */ 

{ VTAG_END_CM, NULL } /* these tags must be filled in */ 

} ; /* before making the call to */ 

/* VideoControl () . */ 

struct Dimensionlnf o dimquery; /* Release 2 structure for display size data */ 

/* Make a ViewPortExtra and get ready to attach it */ 
if( vpextra = GfxNew (VIEWPORT_EXTRA_TYPE) ) 

{ 

vcTags [1] . ti_Data = (ULONG) vpextra; 



/* Initialize the DisplayClip field of the ViewPortExtra structure */ 
if( GetDisplaylnfoDatat NULL , (UBYTE *) Sdimquery , 

sizeof (struct dimquery) , DTAG_DIMS, modelD) ) 

{ 

vpextra->DisplayClip = dimquery .Nominal ; 

/* Make a Displaylnfo and get ready to attach it */ 
if( ! (vcTags [2] . ti_Data = (ULONG) FindDisplaylnf o (modelD) ) ) 
fail ("Could not get Displaylnf o\n" ) ; 

} 
else fail ("Could not get Dimensionlnf o\n" ) ; 
} else fail ("Could not get ViewPortExtra\n" ) ; 

/* This is for backwards compatibility with, for example, */ 
/* a 1.3 screen saver utility that looks at the Modes field */ 
viewport .Modes = (UWORD) (modelD & OxOOOOffff ) ; 

Preparing the ColorMap Structure 

When the View is created, Copper instructions are generated to change the current contents of each color 
register just before the topmost line of a ViewPort so that this Viewport's color registers will be used for 
interpreting its display. To set the color registers you create a ColorMap for the ViewPort with GetColorMap() 
and call SetRGB4(). Here are the steps used in 1 .3 to initialize a ColorMap: 

if ( view.ColorMap=GetColorMap ( 4L ) ) 

LoadRGB4 ( (&viewPort, colortable, 4); 
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Under Release 2, a ColorMap is attached to the View -- usually along with Displaylnfo and ViewExtra -- by 
calling the VideoControl() function. 

/* RGB values for the four colors used. */ 
#define BLACK 0x000 
#define RED OxfOO 
#define GREEN OxOfO 
#define BLUE OxOOf 

/* Define some colors in an array of UWORDS . */ 
static UWORD colortable [] = { BLACK, RED, GREEN, BLUE } ; 

/* Fill the Tagltem Data field with the address of the properly 
initialized (including ViewPortExtra) structure to be passed to 
VideoControl () . */ 

vc [0] .ti_Data = (ULONG) viewport ; 

/* Init ColorMap. 2 planes deep, so 4 entries 

(2 raised to #planes power) . */ 

if (cm = GetColorMap( 4L ) ) 



{ 



/* For applications that must be compatible with 1.3, replace */ 
/* the next 2 lines with: viewport . ColorMap=cm; */ 

if ( VideoControl ( cm , vcTags ) ) 

fail ("Could not attach extended structures\n" ) ; 

/* Change colors to those in colortable. */ 
LoadRGB4 (&viewPort, colortable, 4); 



The 4 Is For Bits, Not Entries. The 4 in the name LoadRGB4() refers to the fact that each of 
the red, green, and blue values in a color table entry consists of four bits. It has nothing to do 
with the fact that this particular color table contains four entries. The call GetRGB4() returns 
the RGB value of a single entry of a ColorMap. SetRGB4CM() allows individual control of the 
entries in the ColorMap before or after linking it into the ViewPort. 



The LoadRGB4() call above could be replaced with the following: 



register USHORT entry; 

/* Operate on the same four ColorMap entries as above. */ 
for (entry = 0; entry < 4; entry++) 

{ 

/* Call SetRGB4CM() with the address of the ColorMap, the entry to 
be changed, and the Red, Green, and Blue values to be stored 
there. */ 
SetRGB4CM (viewport .ColorMap, entry, 

/* Extract the three color values from the one colortable entry. */ 
( (colortable [entry] & OxOfOO) >> 8), 

( (colortable [entry] & OxOOfO) >> 4), 
(colortable [entry] & OxOOOf ) ) ; 
} 

Notice above how the four bits for each color are masked out and shifted right to get values from to 15. 

WARNING! It is important to use only the standard system ColorMap-related calls to access 
the ColorMap entries. These calls will remain compatible with recent and future 
enhancements to the ColorMap structure. 

You might need to specify more colors in the color map than you think. If you use a dual playfield display (covered 
later in this chapter) with a depth of 1 for each of the two playfields, this means a total of four colors (two for each 
playfield). However, because playfield 2 uses color registers starting from number 8 on up when in dual-playfield 
mode, the color map must be initialized to contain at least 10 entries. That is, it must contain entries for colors 
and 1 (for playfield 1) and color numbers 8 and 9 (for playfield 2). Space for sprite colors must be allocated as 
well. For Amiga system software version 1 .3 and earlier, when in doubt, allocate a ColorMap with 32 entries, just 
in case. 
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Creating the Display Instructions 

Now that you have initialized the system data structures, you can request that the system prepare a set of display 
instructions for the Copper using these structures as input data. During the one or more blank vertical lines that 
precede each ViewPort, the Copper is busy changing the characteristics of the display hardware to match the 
characteristics you expect for this ViewPort. This may include a change in display resolution, a change in the 
colors to be used, or other user-defined modifications to system registers. 

Here is the code that creates the display instructions: 

/* Construct preliminary Copper instruction list. */ 
MakeVPort ( &view, &viewPort ) ; 

In this line of code, &view is the address of the View structure and SviewPort is the address of the first ViewPort 
structure. Using these structures, the system has enough information to build the instruction stream that defines 
your display. 

MakeVPort() creates a special set of instructions that controls the appearance of the display. If you are using 
animation, the graphics animation routines create a special set of instructions to control the hardware sprites and 
the system color registers. In addition, the advanced user can create special instructions (called user Copper 
instructions) to change system operations based on the position of the video beam on the screen. 

All of these special instructions must be merged together before the system can use them to produce the display 
you have designed. This is done by the system routine MrgCopQ (which stands for "Merge Coprocessor 
Instructions"). Here is a typical call: 

/* Merge preliminary lists into a real Copper list in the view structure. */ 
MrgCop ( iview ) ; 

Loading and Displaying the View 

To display the View, you need to load it using LoadView() and turn on the direct memory access (DMA). A typical 
call is shown below. 

LoadView (&view) ; 



The &view argument is the address of the View structure defined in the example above. 

There are two macros, defined in <graphics/gfxmacros.h>, that control display DMA: ON_DISPLAY and 
OFF_DISPLAY. They simply turn the display DMA control bit in the DMA control register on or off. 

If you are drawing to the display area and do not want the user to see intermediate steps in the drawing, you can 
turn off the display. Because OFF_DISPLAY shuts down the display DMA and possibly speeds up other system 
operations, it can be used to provide additional memory cycles to the blitter or the 68000. The distribution of 
system DMA, however, allows four-channel sound, disk read/write, and a sixteen-color, low-resolution display (or 
four-color, high-resolution display) to operate at the same time with no slowdown (7.1 megahertz effective rate) in 
the operation of the 68000. Using OFF_DISPLAY in a multitasking environment may, however, be an unfriendly 
thing to do to the other running processes. Use OFF_DISPLAY with discretion. 

Graphic Primitives 555 

A Custom ViewPort Example 

The following example creates a View consisting of one ViewPort set to an NTSC, high-resolution, interlaced 
display mode of nominal dimensions. This example shows both the old 1 .3 way of setting up the ViewPort and 
the new method used in Release 2. 

;/* RGBBoxes.c simple ViewPort example -- works with 1.3 and Release 2 

LC -bl -cfistq -v -y - j 73 RGBBoxes.c 

Blink FROM LIB : c . o, RGBBoxes . o TO RGBBoxes LIBRARY LIB : LC . lib, LIB : Amiga . lib 

quit 

** The following example creates a View consisting of one Viewport set 

** to an NTSC, high-resolution, interlaced display mode of nominal 

** dimensions. This example shows both the old 1.3 way of setting up 

** the ViewPort and the new method used in Release 2. 

*/ 

#include <exec/types .h> 
#include <graphics/gfx.h> 
#include <graphics/gfxbase .h> 
#include <graphics/gfxmacros .h> 
#include <graphics/copper .h> 
#include <graphics/view.h> 
#include <graphics/displayinf o.h> 
#include <graphics/gfxnodes .h> 
#include <graphics/videocontrol .h> 
#include <libraries/dos .h> 
#include <utility/tagitem.h> 

#include <clib/graphics_protos . h> 
#include <clib/exec_protos .h> 
#include <clib/dos_protos .h> 

#include <stdio.h> 
#include <stdlib.h> 

#define DEPTH 2 /* The number of bitplanes. */ 
#define WIDTH 640 /* Nominal width and height */ 
#define HEIGHT 400 /* used in 1 . 3 . */ 

#ifdef LATTICE 

int CXBRK(void) { return(O); } /* Disable Lattice CTRL/C handling */ 

int chkabort (void) { return(O); } /* really */ 

#endif 

VOID drawFilledBox(WORD , WORD ) ; /* Function prototypes */ 
VOID cleanup (int ) ; 
VOID fail (STRPTR) ; 

struct Gf xBase *Gf xBase = NULL; 

/* Construct a simple display. These are global to make freeing easier. */ 
struct View view, *oldview=NULL; /* Pointer to old View we can restore it.*/ 
struct ViewPort viewport = { } ; 



struct BitMap bitMap - { } ; 
struct ColorMap *cm=NULL; 

struct ViewExtra *vextra=NULL; /* Extended structures used in Release 2 */ 
struct MonitorSpec *monspec=NULL; 
struct ViewPortExtra *vpextra=NULL; 
struct Dimensionlnf o dimquery = { } ; 

UBYTE *displaymem = NULL; /* Pointer for writing to BitMap memory. */ 

#define BLACK 0x000 /* RGB values for the four colors used. */ 

#define RED OxfOO 
#define GREEN OxOfO 
#define BLUE OxOOf 

/* 
* main() : create a custom display; works under either 1.3 or Release 2 

*/ 

VOID main (VOID) 

{ 

WORD depth, box; 
struct Raslnfo raslnfo; 
ULONG mode ID; 

struct Tagltem vcTags [] = 

{ 

{VTAG_ATTACH_CM_SET, NULL }, 
{VTAG_VIEWPORTEXTRA_SET, NULL }, 
{VTAG_NORMAL_DISP_SET, NULL }, 
{ VTAG_END_CM , NULL } 



/* Offsets in BitMap where boxes will be drawn. */ 
static SHORT boxof f sets [] = { 802, 2010, 3218 }; 

static UWORD colortable [] = { BLACK, RED, GREEN, BLUE }; 

/* Open the graphics library */ 

GfxBase = (struct GfxBase *) OpenLibrary ( "graphics . library" , 33L) ; 

if(GfxBase == NULL) 

fail ("Could not open graphics library\n"); 

/* Example steals screen from Intuition if Intuition is around. */ 
oldview = GfxBase->ActiView; /* Save current View to restore later. */ 

InitView (&view) ; /* Initialize the View and set View. Modes. */ 

view. Modes |= LACE; /* This is the old 1.3 way (only LACE counts). */ 

if (Gf xBase ->LibNode.lib_Vers ion >= 36) 

{ 

/* Form the ModelD from values in <displayinf o.h> */ 

modeID=DEFAULT_MONITOR_ID | HIRESLACE_KEY; 

/* Make the ViewExtra structure */ 
if( vextra=GfxNew(VIEW_EXTRA_TYPE) ) 

{ 

/* Attach the ViewExtra to the View */ 

GfxAssociate (&view , vextra) ; 

view. Modes |= EXTENDJVSTRUCT ; 

/* Create and attach a MonitorSpec to the ViewExtra */ 
if ( monspec=OpenMonitor (NULL,modeID) ) 

vext ra - >Moni t or =monspec ; 
else 

fail ("Could not get MonitorSpec\n" ) ; 

} 
else fail ("Could not get ViewExtra\n" ) ; 

} 

/* Initialize the BitMap for Raslnfo. */ 
InitBitMap(&bitMap, DEPTH, WIDTH, HEIGHT); 



/* Set the plane pointers to NULL so the cleanup routine */ 
/* will know if they were used. */ 

for (depth=0; depth<DEPTH; depth++) 
bitMap. Planes [depth] = NULL; 

/* Allocate space for BitMap. */ 

for (depth=0; depth<DEPTH; depth++) 

{ 

bitMap. Planes [depth] = (PLANEPTR) AllocRaster (WIDTH, HEIGHT); 

if (bitMap. Planes [depth] == NULL) 

fail ("Could not get BitPlanes\n" ) ; 
} 

raslnfo. BitMap = &bitMap; /* Initialize the Raslnfo. */ 
rasInfo.RxOf f set = 0; 
raslnfo. RyOf f set = 0; 
raslnfo. Next = NULL; 

InitVPort (SviewPort) ; /* Initialize the Viewport. */ 

view. Viewport = SviewPort; /* Link the Viewport into the View. */ 

viewport .Raslnfo = &rasInfo; 

viewport .DWidth = WIDTH; 

viewport .DHeight = HEIGHT; 

/* Set the display mode the old-fashioned way */ 
viewport .Modes=HIRES | LACE; 

if (GfxBase->LibNode . lib_Version >= 36) 

{ 

/* Make a ViewPortExtra and get ready to attach it */ 
if( vpextra = GfxNew (VIEWPORT_EXTRA_TYPE) ) 

{ 

vcTags [1] . ti_Data = (ULONG) vpextra; 

/* Initialize the DisplayClip field of the ViewPortExtra */ 
if ( GetDisplaylnfoDatat NULL , (UBYTE *) Sdimquery , 

sizeof (dimquery) , DTAG_DIMS, modelD) ) 

{ 

vpextra->DisplayClip = dimquery .Nominal ; 

/* Make a Displaylnfo and get ready to attach it */ 
if ( ! (vcTags [2] .ti_Data = (ULONG) FindDisplaylnf o (modelD) ) ) 
fail ("Could not get Displaylnf o\n" ) ; 

} 
else fail ("Could not get Dimensionlnf o \n"); 

} 
else fail ("Could not get ViewPortExtra\n" ) ; 

/* This is for backwards compatibility with, for example, */ 
/* a 1.3 screen saver utility that looks at the Modes field */ 
viewport .Modes = (UWORD) (modelD & OxOOOOffff ) ; 



/* Initialize the ColorMap. */ 

/* 2 planes deep, so 4 entries (2 raised to the #_planes power) . */ 

cm = GetColorMap(4L) ; 

if (cm == NULL) 

fail ("Could not get ColorMap\n" ) ; 

if (GfxBase->LibNode . lib_Version >= 36) 

{ 

/* Get ready to attach the ColorMap, Release 2-style */ 

vcTags [0] .ti_Data = (ULONG) SviewPort ; 

/* Attach the color map and Release 2 extended structures */ 
if ( VideoControl (cm, vcTags) ) 

fail ("Could not attach extended structures\n" ) ; 

} 
else 

/* Attach the ColorMap, old 1.3-style */ 
viewport .ColorMap = cm; 



LoadRGB4 (&viewPort , colortable, 4); /* Change colors to those in colortable. */ 

MakeVPort ( &view, SviewPort ); /* Construct preliminary Copper instruction list. */ 

/* Merge preliminary lists into a real Copper list in the View structure. */ 
MrgCop ( &view ) ; 

/* Clear the Viewport */ 

for (depth=0; depth<DEPTH; depth++) 

{ 

displaymem = (UBYTE *) bitMap. Planes [depth] ; 

BltClear (displaymem, (bitMap. BytesPerRow * bitMap. Rows) , 1L) ; 

} 

LoadView (&view) ; 

/* Now fill some boxes so that user can see something. */ 

/* Always draw into both planes to assure true colors. */ 

for (box=l; box<=3; box++) /* Three boxes; red, green and blue. */ 

{ 

for (depth=0; depth<DEPTH; depth++) /* Two planes. */ 

{ 

displaymem = bitMap. Planes [depth] + boxof f sets [box-1] ; 
drawFilledBox (box, depth); 
} 
} 

Delay(10L * TICKS_PER_SECOND) ; /* Pause for 10 seconds. */ 

LoadView (oldview) ; /* Put back the old View. */ 

WaitTOFO; /* Wait until the the View is being */ 

/* rendered to free memory. */ 

FreeCprList (view.LOFCprList) ; /* Deallocate the hardware Copper list */ 

if (view.SHFCprList) /* created by MrgCop () . Since this */ 

FreeCprList (view. SHFCprList) ; /* is interlace, also check for a */ 

/* short frame copper list to free. */ 

FreeVPortCopLists (SviewPort) ; /* Free all intermediate Copper lists */ 

/* from created by MakeVPort ( ) . */ 

cleanup (RETURNJOK) ; /* Success. */ 

} 

/* 

* fail() : print the error string and call cleanup () to exit 

*/ 

void fail (STRPTR errorstring) 

{ 

printf (errorstring) ; 

cleanup (RETURN_FAIL) ; 

} 

/* 

* cleanup () : free everything that was allocated. 

*/ 

VOID cleanup (int returncode) 

{ 

WORD depth; 

/* Free the color map created by GetColorMap ( ) . */ 
if (cm) FreeColorMap (cm) ; 

/* Free the ViewPortExtra created by Gf xNew ( ) */ 
if (vpextra) GfxFree (vpextra) ; 

/* Free the BitPlanes drawing area. */ 
for(depth=0; depth<DEPTH; depth++) 

{ 

if (bitMap. Planes [depth] ) 

FreeRaster (bitMap. Planes [depth] , WIDTH, HEIGHT); 
} 

/* Free the MonitorSpec created with OpenMonitor ( ) */ 
if (monspec) CloseMonitor ( monspec ); 



/* Free the ViewExtra created with Gf xNew ( ) */ 
if (vextra) GfxFree (vextra) ; 

/* Close the graphics library */ 
CloseLibrary ( (struct Library *)GfxBase); 

exit (returncode) ; 
} 

/* 

* drawFilledBoxO : create a WIDTH/2 by HEIGHT/2 box of color 

* "fillcolor" into the given plane. 

*/ 

VOID drawFilledBox(WORD fillcolor, WORD plane) 

{ 

UBYTE value; 

WORD boxHeight, boxWidth, width; 

/* Divide (WIDTH/2) by eight because each UBYTE that */ 
/* is written stuffs eight bits into the BitMap. */ 
boxWidth = (WIDTH/2) /8; 
boxHeight = HEIGHT/2; 

value = ((fillcolor & (1 << plane)) != 0) ? Oxff : 0x00; 

fort ; boxHeight; boxHeight--) 

{ 

for(width=0 ; width < boxWidth; width++) 
*displaymem++ = value; 

displaymem += (bitMap.BytesPerRow - boxWidth); 
} 
} 
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Exiting Gracefully 

The preceding sample program provides a way of exiting gracefully with the cleanup() subroutine. This function 
returns to the memory manager all dynamically-allocated memory chunks. Notice the calls to FreeRaster() and 
FreeColorMap(). These calls correspond directly to the allocation calls AllocRasterQ and GetColorMap() 
located in the body of the program. Now look at the calls within cleanup() to FreeVPortCopLists() and 
FreeCprListQ. When you call MakeVPort(), the graphics system dynamically allocates some space to hold 
intermediate instructions from which a final Copper instruction list is created. When you call MrgCopQ, these 
intermediate Copper lists are merged together into the final Copper list, which is then given to the hardware for 
interpretation. It is this list that provides the stable display on the screen, split into separate Viewports with their 
own colors and resolutions and so on. 

When your program completes, you must see that it returns all of the memory resources that it used so that those 
memory areas are again available to the system for reassignment to other tasks. Therefore, if you use the 
routines MakeVPort() or MrgCop(), you must also arrange to use FreeCprList() (pointing to each of those lists in 
the View structure) and FreeVPortCopListsQ (pointing to the ViewPort that is about to be deallocated). If your 
View is interlaced, you will also have to call FreeCprList(&view.SHFCprList) because an interlaced view has a 
separate Copper list for each of the two fields displayed. Do not confuse FreeVPortCopListsQ with 
FreeCprListQ. The former works on intermediate Copper lists for a specific ViewPort, the latter directly on a 
hardware Copper list from the View. 

As a final caveat, notice that when you do free everything, the memory manager or other programs may 
immediately change the contents of the freed memory. Therefore, if the Copper is still executing an instruction 
stream (as a result of a previous LoadViewQ) when you free that memory, the display will malfunction. Once 
another View has been installed via LoadView(), do a WaitTOF() for the new View to begin displaying, and then 
you can begin freeing up your resources. WaitTOF() waits for the vertical blanking period to begin and all vertical 
blank interrupts to complete before returning to the caller. The routine WaitBOVP() (for "WaitBottomOfViewPort") 
busy waits until the vertical beam reaches the bottom of the specified ViewPort before returning to the caller. 
This means no other tasks run until this function returns. 



Monitors Modes, and the Display Database 

The Release 2 graphics library supports a variety of new video monitors, and new programmable video modes not 
available in older versions of the operating system. Inquiries about the availability of these modes, their 
dimensions and currently accessible options can be made through a database indexed by the same key 
information used to open Intuition screens. This design provides a good degree of compatibility with existing 
software, between differently equipped hardware platforms and for both static and dynamic data storage. 

The Release 2 software may be running on A1000 computers which will not have ECS, on A500 computers which 
may not have the latest ECS upgrade, and on A2000 computers which generally have the latest ECS but may not 
have a multi-sync monitor currently attached. This means that there are compatibility issues to consider-what 
should happen when a required ECS or monitor resource is not available for the desired mode. 
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Here are the compatibility criteria, in a simplified fashion: 

Requires Release 2, and ECS Chips only 

SuperHires mode (35nS pixel resolutions). This allows for very high horizontal resolutions with the new 
ECS chip set and a standard NTSC or PAL monitor. (SuperHires has twice as much horizontal 
resolution as the old Hires mode.) 

Requires Release 2, ECS Chips, and appropriate monitor 

Productivity mode. This allows for flicker-free 640 x 480 color displays with the addition of a multi-sync 
or bi-sync 31 Khz monitor. (Productivity mode conforms, in a general way, to the VGA Mode 3 Standard 
851 4/A.) 

Requires Release 2 (or the V35 of graphics.library under 1.3) and appropriate monitor only 

A2024 Scan Conversion. This allows for a very high resolution grayscale display, typically 1008x800, 
suitable for desktop publishing or similar applications. A special video monitor is required (the monitor 
also supports the normal Amiga modes in greyscale). 

Requires Release 2 but not ECS Chips or appropriate monitor 

Display database inquiries. This allows for programmers to determine if the required resources are 
currently available for the requested mode. 

In addition, there are fallback modes (which do not require Release 2) which resort to some reasonable display 
when a required resource is not available. 

New Monitors 

Currently, there are five possible monitor settings in the display database (more may be added in future releases): 

default.monitor 

Since the default system monitor must be capable of displaying an image no matter what chips are 
installed or what software revision is in ROM, the graphics.library default.monitor is defined as a 15 Khz 
monitor which can display NTSC in the U.S. or PAL in Europe. 

ntsc.monitor 

Since the ECS chip set allows for dynamic choice of standard scan rates, NTSC applications running 
on European machines may choose to be displayed on the ntsc.monitor to preserve the aspect ratio. 

pal. monitor 

Since the ECS chip set allows for dynamic choice of standard scan rates, PAL applications running on 
American machines may choose to be displayed on the pal. monitor to preserve the aspect ratio. 

multisync.monitor 

Programmably variable scan rates from 15 Khz through 31 Khz or more. Responds to signal timings to 
decide what scan rate to display. Required for Productivity (640 x 480 x 2 non-interlaced) display. 

A2024.monitor 

Scan converter monitor which provides 1008 x 800 x 2 (U.S.) or 1008 x 1024 x 2 (European) 
high-resolution, greyscale display. Does not require ECS. Does require Release 2 (or 1.3 V35) 
graphics library. 
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New Modes 

In V1 .3 and earlier versions of the OS, the mode for a display was determined by a 16 bit-value specified either in 
the ViewPort. Modes field (for displays set up with the graphics library) or in the NewScreen.ViewModes field 
(for displays set up with Intuition). Prior to Release 2, it was sufficient to indicate the mode of a display by setting 
bits in the ViewPort.Modes field. Furthermore, programs routinely made interpretations about a given display 
mode based on bit-by-bit testing of this 16-bit value. 

Table 27-4: ViewPort Modes Used in 1.3 

Bit Name 1 . 3 ViewPort Modes 



15 

14 

13 VPHIDE DC R = respected by 1 . 3 

12 reserved IP I = ignored by 1.3 

11 HAM RP D = dynamic 

10 DUALPF RP C = cleared on write by 1 . 3 

9 reserved IP IFF writers 

preserved on write by 1 . 3 



HIRES 


RP 


SPRITE 


DC 


VPHIDE 


DC 


reserved 


IP 


HAM 


RP 


DUALPF 


RP 


reserved 


IP 


GENATJD 


IC 


EHB 


RP 


PFBA (PF2PRI) 


RP 


reserved 


IP 


reserved 


IP 


reserved 


IP 


LACE 


RP 


GENVID 


IC 


reserved 


IP 



7 EHB RP IFF writers 

6 

5 

4 

3 

2 

1 



Considering all the possible new mode combinations and the need for future expansion, it is clear that the 16-bit 
mode specification used in 1 .3 needs to be extended. Also, the specification of a mode needs to be separated 
from its interpretation. Furthermore, since modes can be grouped by the special monitor or physical device 
needed for the display, it is also beneficial to make provisions to support additional monitors and their modes in 
the future. 

The approach taken in Release 2 is to introduce a new 32-bit display mode specifier called a ModelD. The upper 
half of this specifier is called the monitor part and the lower half is informally called the mode part. There is a 
correspondence between the monitor part and the monitor's operating modes (referred to as virtual monitors or 
MonitorSpecs after a system data structure). 

For example, the A2024 monitor, PAL and NTSC are all different virtual monitors-the actual, physical monitor 
may be able to support more than one of these virtual types. Another new concept in Release 2 is the default 
monitor. The default monitor, represented by a zero value for the ModelD monitor part, may be either PAL or 
NTSC depending on a jumper on the motherboard. 

Compatibility considerations-especially for IFF files and their CAMG chunk-have dictated very careful choices for 
the bit values which make up the mode part of the 32-bit ModelDs. For example, the ModelDs corresponding to 
the older, 1.3 display modes have been constructed out of a zero in the monitor part and the old 16-bit 
ViewPort.Modes bits in the lower part (after several extraneous bits such as SPRITES and VP_HIDE are 
cleared). 
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There are other such coincidences, but steps for compatibility with old programs notwithstanding, there is a new 
rule: 

Programmers shall never interpret ModelDs on a bit-by-bit basis. 

For example, if the HIRES bit is set it does not mean the display is 640 pixels wide because there can also be a 
doubling of the beam scan rate under Release 2. Programs should not attempt to interpret modes directly from 



the ViewPort.Modes field. The Release 2 graphics library provides a suitable substitute for this information 
through its new display database facility (explained below). 

Likewise, under Release 2, the Mode of a ViewPort is no longer set directly. Instead it is set indirectly by 
associating the ViewPort with an abstract, 32-bit ModelD via the VideoControl() function. 

These 32-bit ModelDs have been carefully designed so that their lower 16 bits, when passed to graphics in the 
ViewPort.Modes field, provide some degree of compatibility between different systems. Older V1 .3 programs will 
continue to work within the new scheme. (They will, however, not gain the benefits of the new modes and 
monitors available.) 

Table 27-5: Extended ViewPort Modes Used in Release 2 



Bit 



Name 



Release 2 ViewPort Modes 



15 


MDBIT9 


RP 






14 


SPRITE 


DC 






13 


VPHIDE 


DC 


R 


= respected by Release 


12 


EXTEND 


RP 


I 


= ignored by Release 2 


11 


MDBIT8 


RP 


D 


= dynamic 


10 


MDBIT7 


RP 


C 


= cleared on write by 


9 


MDBIT6 


RP 




Release 2 IFF writers 


8 


reserved 


IC 


P 


= preserved on write by 


7 


MDBIT5 


RP 




Release 2 IFF writers 


6 


PF2PRI 


RP 






5 


MDBIT4 


RP 






4 


MDBIT3 


RP 






3 


MDBIT2 


RP 






2 


MDBIT1 


RP 






1 


reserved 


IC 









MDBITO 


RP 







Refer to the example program, WBCIone.c, at the end of this section for examples on opening Release 2 
Viewports using the new ModelD specification. 

Mode Specification, Screen Interface 

Opening an Intuition screen in one of the new modes requires the specification of 32 bits of mode data. The 
NewScreen.ViewModes field is a UWORD (16 bits). Therefore, the new Release 2 function OpenScreenTags() 
must be used along with a SA_DisplaylD tag which specifies the 32-bit ModelD. See the "Intuition Screens" 
chapter for more on this. 
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The new display modes also introduce some complexity for applications that want to support "mode-sensitive" 
processing. If a program wishes to open a screen in the highest resolution that a user has available, there are 
many more cases to handle under Release 2. Therefore, it will become increasingly important to algorithmically 
layout a screen for correct, functional and aesthetic operation. All the information needed to be mode-flexible is 
available through the display database functions (explained below). 

Mode Specification, ViewPort Interface 

When working directly with graphics, the interface is based on View and ViewPort structures, rather than on 
Intuition's Screen structure. As previously mentioned, new information must be associated with the ViewPort to 
specify the new Release 2 modes, and also with the View to specify what virtual monitor the whole View will be 
displayed on. There is also a lot of information to associate with a ViewPort regarding enhanced genlock 
capabilities. 

This association of this new data with the View is made through a display database system which has been 
added to the Release 2 graphics library. All correctly written programs that allocate a ColorMap structure for a 
ViewPort use the GetColorMap() function to do it. Hence, in Release 2 the ColorMap structure is used as the 
general purpose black box extension of the ViewPort data. 

To set or obtain the data in the extended structures, Release 2 provides a new function named VideoControl() 



which takes a ColorMap as an argument. This allows the setting and getting of the new extended display data. 
This mechanism is used to associate a Displaylnfo handle {not a ModelD) with a ViewPort. A Displaylnfo 
handle is an abstract link to the display database area associated with a particular ModelD. This handle is 
passed to the graphics database functions when getting or setting information about the mode. Using 
VideoControlQ, a program can enable, disable, or obtain the state of a Viewport's ColorMap, mode, genlock 
and other features. The function uses a tag based interface and returns NULL if no error occurred. 

error = BOOL VideoControl ( struct ColorMap *cm, struct Tagltem *tag ) ; 

The first argument is a pointer to a ColorMap structure as returned by the GetColorMapO function. The second 
argument is a pointer to an array of video control tag items, used to indicate whether information is being given or 
requested as well as to pass (or receive the information). The tags you can use with VideoControl() include the 
following: 

VTAG_ATTACH_CM_GET (or_SET) is used to obtain the ColorMap structure from the indicated ViewPort or 
attach a given ColorMap to it. 

VTAG_VIEWPORTEXTRA_GET (or _SET) is used to obtain the ViewPortExtra structure from the indicated 
ColorMap structure or attach a given ViewPortExtra to it. A ViewPortExtra structure is an extension of the 
ViewPort structure and should be allocated and freed with GfxNewQ and GfxFreeQ and associated with the 
ViewPort with VideoControl(). 

VTAG_NORMAL_DISP_GET (or _SET) is used to obtain or set the Displaylnfo structure for the standard or 
"normal" mode. 

See <graphics/videocontrol.h> for a list of all the available tags. See the section on genlocking for information on 
using VideoControl() to interact with the Amiga's genlock capabilities. Note that the graphics library will modify 
the tag list passed to VideoControl(). 
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Coexisting Modes 

Each display mode specifies (among other things) a pixel resolution and a monitor scan rate. Though the Amiga 
has the unique ability to change pixel resolutions on the fly, it is not possible to change the speed of a monitor 
beam in mid-frame. Therefore, if you set up a display of two or more Viewports in different display modes 
requiring different scan rates, at least one of the Viewports will be displayed with the wrong scan rate. 

Such Viewports can be coerced into a different mode designed for the scan rate currently in effect. You can do 
this in a couple of ways, introducing or removing interlace to adjust the vertical dimension, and changing to faster 
or slower pixels (higher or lower resolution) for the horizontal dimension. 

The disadvantage of introducing interlace is flicker. The disadvantage of increasing resolution is the lessening of 
the video bus bandwidth and possibly a reduction in the number of colors or palette resolution. 

Under Intuition, the frontmost screen determines which of the conflicting modes will take precedence. With the 
graphics library, the Modes field of the View and its frontmost ViewPort or, in Release 2, the MonitorSpec of the 
ViewExtra determine the scan rate. For some monitors (such as the A2024), simultaneous display is excluded. 
This is a requirement only because the A2024 modes require very special and intricate display Copper list 
management. 

ModelD Indentifiers 

The following definitions appear in the include file <graphics/displayinfo.h>. These values form the 32-bit ModelD 
which consists of a _MONITOR_ID in the upper word, and a _MODE_KEY in the lower word. Never interpret 
these bits directly. Instead use them with the display database to obtain the information you need about the 
display mode. 

/* normal identifiers */ 

#define MONITOR_ID_MASK OxFFFFlOOO 

#define DEFAULT_MONITOR_ID 0x00000000 

#define NTSC_MONITOR_ID 0x00011000 

#define PAL MONITOR ID 0x00021000 



/* the following 20 composite keys are for Modes on the default */ 

/* Monitor NTSC & PAL "flavors" of these particular keys may be */ 

/* made by OR' ing the NTSC or PAL MONITOR_ID with the desired */ 

/ * MODE KEY ... * / 



#define LORES_KEY 
#define HIRES_KEY 
#define SUPER_KEY 
#define HAM_KEY 
#define LORESLACE_KEY 
#define HIRESLACE_KEY 
#define SUPERLACE_KEY 
#define HAMLACE_KEY 
#define LORESDPF_KEY 
#define HIRESDPF_KEY 
#define SUPERDPF_KEY 
#define LORESLACEDPF_KEY 
#define HIRESLACEDPF_KEY 
#define SUPERLACEDPF_KEY 
#define LORESDPF2_KEY 
#define HIRESDPF2_KEY 
#define SUPERDPF2_KEY 
#define LORESLACEDPF2_KEY 
#define HIRESLACEDPF2_KEY 
#define SUPERLACEDPF2_KEY 
#define EXTRAHALFBRITE_KEY 
#define EXTRAHALFBRITELACE KEY 



0x00 
0x00 
0x00 
0x00 
0x00 
0x00 
0x00 
0x00 
0x00 
0x00 
0x00 
0x00 
0x00 
0x00 
0x00 
0x00 
0x00 
0x00 
0x00 
0x00 
0x00 
0x00 



000000 
008000 
008020 
000800 
000004 
008004 
008024 
000804 
000400 
008400 
008420 
000404 
008404 
008424 
000440 
008440 
008460 
000444 
008444 
008464 
000080 
000084 
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/* vga identifiers */ 

#define VGA_MONITOR_ID 

#define VGAEXTRALORES_KEY 
#define VGALORES_KEY 
#define VGAPRODUCT_KEY 
#define VGAHAM_KEY 
#define VGAEXTRALORESLACE_KEY 
#define VGALORESLACE_KEY 
#define VGAPRODUCTLACE_KEY 
#define VGAHAMLACE_KEY 
#define VGAEXTRALORESDPF_KEY 
#define VGALORESDPF_KEY 
#define VGAPRODUCTDPF_KEY 
#define VGAEXTRALORESLACEDPF_KEY 
#define VGALORESLACEDPF_KEY 
#define VGAPRODUCTLACEDPF_KEY 
#define VGAEXTRALORESDPF2_KEY 
#define VGALORESDPF2_KEY 
#define VGAPRODUCTDPF2_KEY 
#define VGAEXTRALORESLACEDPF2_KEY 
#define VGALORESLACEDPF2_KEY 
#define VGAPRODUCTLACEDPF2_KEY 
#define VGAEXTRAHALFBRITE_KEY 
#define VGAEXTRAHALFBRITELACE KEY 



0x00031000 


0x00031004 


0x00039004 


0x00039024 


0x00031804 


0x00031005 


0x00039005 


0x00039025 


0x00031805 


0x00031404 


0x00039404 


0x00039424 


0x00031405 


0x00039405 


0x00039425 


0x00031444 


0x00039444 


0x00039464 


0x00031445 


0x00039445 


0x00039465 


0x00031084 


0x00031085 



/* a2024 identifiers */ 
#define A2024 MONITOR ID 



0x00041000 



#define A2 024TENHERTZ_KEY 
#define A2024FIFTEENHERTZ KEY 



0x00041000 
0x00049000 



/* prototype identifiers */ 
#define PROTO MONITOR ID 



0x00051000 



The Display Database and the Displaylnfo Record 

For each ModelD, the graphics library has a body of data that enables the set up of the display hardware and 



provides applications with information about the properties of the display mode. 

The display information in the database is accessed by searching it for a record with a given ModelD. For 
performance reasons, a look-up function named FindDisplaylnfo() is provided which, given a ModelD, will return 
a handle to the internal data record about the attributes of the display. 

This handle is then used for queries to the display database and specification of display mode to the low-level 
graphics routines. It is never used as a pointer. The private data structure associated with a given ModelD is 
called a Displaylnfo. From the <graphics/displayinfo.h> include file: 

/* the "public" handle to a Displaylnfo */ 
typedef APTR DisplaylnfoHandle; 

In order to obtain database information about an existing ViewPort, you must first gain reference to its 32-bit 
ModelD. A graphics function GetVPModelDQ simplifies this operation: 

modelD = ULONG GetVPModelD (struct Viewport *vp ) 

The vp argument is pointer to a ViewPort structure. This function returns the normal display ModelD, if one is 
currently associated with this ViewPort. If no ModelD exists this function returns INVALIDJD. 
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Each new valid 32-bit ModelD is associated with data initialized by the graphics library at powerup. This data is 
accessed by obtaining a handle to it with the graphics function FindDisplaylnfo(). 

handle = Displaylnf oHandle FindDisplaylnf o (ULONG modelD) ; 

Given a 32-bit ModelD key (modelD in the prototype above) FindDisplaylnfo() returns a handle to a valid 
DisplaylnfoRecord found in the graphics database, or NULL. Using this handle, you can obtain information 
about this video mode, including its default dimensions, properties and whether it is currently available for use. 

For instance, you can use a DisplaylnfoHandle with the GetDisplaylnfoData() function to look up the properties 
of a mode (see below). Or use the DisplaylnfoHandle w it h VideoControl() and the 
VTAG_NORMAL_DISP_SET tag to set up a custom ViewPort. 

Accessing the Displaylnfo 

Basic information about a display can be obtained by calling the Release 2 graphics function 
GetDisplaylnfoDataQ. You also call this function during the set up of a ViewPort. 

result = ULONG GetDisplaylnfoData ( DisplaylnfoHandle handle, UBYTE *buf, 

ULONG size, ULONG tag ID, ULONG mode ID ) 

Set the handle argument to the DisplaylnfoHandle returned by a previous call to FindDisplaylnfoQ. This 
function will also accept a 32-bit ModelD directly as an argument. The handle argument should be set to NULL in 
that case. 

The buf argument points to a destination buffer you have set up to hold the information about the properties of the 
display. The size argument gives the size of the buffer which depends on the type of inquiry you make. 

The tagID argument specifies the type information you want to know about and may be set as follows: 

DTAG_DISP Returns display properties and availability information (the buffer should be set to the size of a 
Displaylnfo structure). 

DTAG_DIMS Returns default dimensions and overscan information (the buffer should be set to the size of a 
Dimensionlnfo structure). 

DTAG_MNTR Returns monitor type, view position, scan rate, and compatibility (the buffer should be set to the 
size of a Monitorlnfo structure). 

DTAG_NAME Returns the user friendly name for this mode (the buffer should be set to the size of a 
Namelnfo structure). 



If the call succeeds, result is positive and reports the number of bytes actually transferred to the buffer. If the call 
fails (no information for the ModelD was available), result is zero. 

Graphics Primitives 567 

Modes Availability 

Even if the video monitor (NTSC, PAL, VGA, A2024) or ECS chips required to support a given mode are not 
available, there will be a Displaylnfo for all of the display modes. (This will not be the case for disk-based modes 
such as Euro36, Euro72, etc.) 

Thus, the graphics library provides the ModeNotAvailable() function to determine whether a given mode is 
available, and if not, why not. Data corruption might cause the look-up function, GetVPModelDQ. to fail even 
when it should not, so the careful programmer will always test the look-up function's return value. 

error = ULONG ModeNotAvailable ( ULONG modelD ) 

The modelD argument is again a 32-bit ModelD as shown in <graphics/displayinfo.h>. This function returns an 
error code, indicating why this modelD is not available, or NULL if there is no known reason why this mode should 
not be there. The ULONG return values from this function are a proper superset of the 
Displaylnfo. NotAvailable field (defined in <graphics/displayinfo.h>). 

The graphics library checks for the presence of the ECS chips at power up, but the monitor attached to the 
system cannot be detected and so must be specified by the user through a separate utility named AddMonitor. 

Accessing the MonitorSpec 

The OpenMonitor() function will locate and open the requested MonitorSpec. It is called with either the name of 
the monitor or a ModelD. 

mspc = struct MonitorSpec *OpenMonitor (STRPTR name, ULONG modelD) 

If the name argument is non-NULL, the MonitorSpec is chosen by name. If the name argument is NULL, the 
MonitorSpec is chosen by ModelD. If both the name and ModelD arguments are NULL, a pointer to the 
MonitorSpec for the default monitor is returned. OpenMonitorQ returns either a pointer to a MonitorSpec 
structure, or NULL if the requested MonitorSpec could not be opened. The CloseMonitorQ function relinquishes 
access to a MonitorSpec previously acquired with OpenMonitor(). 

To set up a View in Release 2, a ViewExtra structure must also be created and attached to it. The 
ViewExtra. Monitor field must be initialized to the address of a valid MonitorSpec structure before the View is 
displayed. Use OpenMonitor() to initialize the Monitor field. 

Mode Properties 

Here is an example of how to query the properties of a given mode from a DisplaylnfoHandle. 

# include <graphi cs/di splay inf o.h> 

check_properties ( handle ) 
DisplaylnfoHandle handle; 

{ 

struct Displaylnfo queryinfo; 

/* fill in the displayinfo buffer with basic Mode display data */ 

if (GetDisplaylnf oData (handle, (UBYTE *) &queryinfo, sizeof (queryinfo) , 
DTAG_D ISP, NULL) ) ) 
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{ 

/* check for Properties of this Mode */ 

if (queryinfo. Proper tyFlags) 
{ 



if (queryinfo.PropertyFlags & DIPF_IS_LACE) 

printf ( "mode is interlaced"); 
if (queryinfo.PropertyFlags & DIPF_IS_DUALPF) 

printf ("mode has dual playf ields" ) ; 
if (queryinfo.PropertyFlags & DIPF_IS_PF2PRI) 

printf ("mode has playf ield two priority"); 
if (queryinfo.PropertyFlags & DIPF_IS_HAM) 

printf ("mode uses hold-and-modify" ) ; 
if (queryinfo.PropertyFlags & DIPF_IS_ECS) 

printf ("mode requires the ECS chip set"); 
if (queryinfo.PropertyFlags & DIPF_IS_PAL) 

printf ("mode is naturally displayed on pal .monitor" ) 
if (queryinfo.PropertyFlags & DIPF_IS_SPRITES) 

printf ("mode has sprites"); 
if (queryinfo.PropertyFlags & DIPF_IS_GENLOCK) 

printf ("mode is compatible with genlock displays"); 
if (queryinfo.PropertyFlags & DIPF_IS_WB) 

printf ("mode will support workbench displays"); 
if (queryinfo.PropertyFlags & DIPF_IS_DRAGGABLE) 

printf ("mode may be dragged to new positions"); 
if (queryinfo.PropertyFlags & DIPF_IS_PANELLED) 

printf ("mode is broken up for scan conversion"); 
if (queryinfo.PropertyFlags & DIPF_IS_BEAMSYNC) 

printf ("mode supports beam synchronization"); 



Nominal Values 

Some of the display information is initialized in ROM for each mode such as recommended nominal (or default) 
dimensions. Even though this information is presumably static, it would still be a mistake to hardcode 
assumptions about these nominal values into your code. 

Gathering information about the nominal dimensions of various modes is handled in a fashion similar to to the 
basic queries above. Here is an example of how to query the nominal dimensions of a given mode from a 
DisplaylnfoHandle. 

# include <graphi cs/di splay inf o.h> 

check_dimensions ( handle ) 
DisplaylnfoHandle handle; 

{ 

struct Dimensionlnf o query; 

/* fill the buffer with Mode dimension information */ 

if (GetDisplaylnfoData (handle, (UBYTE *) &query, sizeof (query) , 
DTAG DIMS, NULL) ) ) 



{ 



} 



/* display Nominal dimensions of this Mode */ 

printf ( "nominal width = %ld", 

query .Nominal .MaxX - query .Nominal .MinX + 1) 

printf ( "nominal height = %ld", 

query .Nominal .MaxY - query .Nominal .MinY + 1) 
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Preference Items 

Some display information is changed in response to user Preference specification. Until further notice, this will be 
reserved as a system activity and use private interface methods. 

One Preferences setting that may affect the display data is the user's preferred overscan limits to the monitor 
associated with this mode. Here is an example of how to query the overscan dimensions of a given mode from a 
DisplaylnfoHandle. 



# include <graphi cs/di splay inf o.h> 

check_overscan ( handle ) 
Displaylnf oHandle handle; 

{ 

struct Dimensionlnf o query; 

/* fill the buffer with Mode dimension information */ 

if (GetDisplaylnfoData (handle, (UBYTE *) &query, sizeof (query) , 
DTAG_DIMS,NULL) ) ) 

{ 

/* display standard overscan dimensions of this Mode */ 

printf ( "overscan width = %ld", 

query. StdOScan.MaxX - query . StdOScan.MinX + 1) ; 

printf ( "overscan height = %ld", 

query. StdOScan.MaxY - query . StdOScan.MinY + 1); 
} 
} 

Run-Time Name Binding of Mode Information 

It is useful to associate common names with the various display modes. The Release 2 graphics library includes a 
provision for binding a name to a display mode so that it will be available via a query. This will be useful in the 
implementation of a standard screen-format requester. Note however that no names are bound initially since the 
bound names will take up RAM at all times. Instead defaults are used. 

Bound names will override the defaults though, so that, until the screen-format requester is localized to a 
non-English language, the modes can be localized by binding foreign language names to them. Here is an 
example of how to query the run-time name binding of a given mode from a DisplaylnfoHandle. 

# include <graphi cs/di splay inf o.h> 

check_name_bound ( handle ) 
DisplaylnfoHandle handle; 

{ 

struct Namelnfo query; 

/* fill the buffer with Mode dimension information */ 

if (GetDisplaylnfoData (handle, (UBYTE *) &query, sizeof (query) , 
DTAG_NAME , NULL) ) ) 

{ 

printf ("%s", que ry. Name ) ; 

} 
} 
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Release 2 Custom ViewPort Example 

The following program will create a display with the same attributes as the user's Workbench screen. It does this 
by inquiring as to those attributes, duplicating them, and the creating a simular display. 

/* The following program will create a display with the same attributes 
** as the user's Workbench screen. It does this by first inquiring as 
** to those attributes, duplicating them, and then creating a similar 
** display. 
*/ 

/**********************^ 

/* */ 

/* WBClone.c: To clone the Workbench using graphics calls */ 

/* */ 

/* Compile : SAS/C 5.10a LC -bl -cfist -L -v -y */ 

/* */ 



#include <exec/types .h> 
#include <exec/exec . h> 
#include <clib/exec_protos . h> 
#include <intuition/screens .h> 
#include <intuition/intuition.h> 
#include <intuition/intuitionbase . h> 
#include <clib/intuition_protos . h> 
#include <graphics/gfx.h> 
#include <graphics/gfxbase . h> 
#include <graphics/view.h> 
#include <graphics/gfxnodes .h> 
#include <graphics/videocontrol . h> 
#include <clib/graphics_protos . h> 

#include <stdio.h> 
#include <stdlib.h> 

#define INTUITIONNAME " intuition . library" 

#ifdef LATTICE 

int CXBRK(void) { return(O); } /* Disable Lattice CTRL/C handling */ 

int chkabort (void) { return(O) ; } /* really */ 

#endif 

/**'**'**'****'**'**'****'**'**'****'*'* 

/* GLOBAL VARIABLES */ 

/*********************************************************************/ 

struct IntuitionBase *IntuitionBase = NULL ; 
struct GfxBase *GfxBase = NULL ; 

/* */ 

/* VOID Error (char *String) */ 

/* */ 

/* Print string and exit */ 

/* " */ 

/*'*'*'*'*'****'***'**'**'********'****** 

VOID Error (char *String) 

{ 

VOID CloseAll (VOID) ; 

printf (String) ; 

CloseAll () ; 
exit(O) ; 
} 

/* */ 

/* VOID Init () */ 

/* */ 

/* Opens all the required libraries allocates all memory, etc. */ 

/* * */ 

/**********************************************************************/ 

VOID Init ( VOID ) 

{ 

/* Open the intuition library. ... */ 

if ((IntuitionBase = (struct IntuitionBase *) OpenLibrary (INTUITIONNAME, 37L) ) == NULL) 
Error ("Could not open the Intuition. library" ) ; 

/* Open the graphics library. ... */ 

if ((GfxBase = (struct GfxBase *) OpenLibrary (GRAPHICSNAME, 36L)) == NULL) 
Error ("Could not open the Graphics . library" ) ; 
} 

/* */ 

/* VOID CloseAll () */ 

/* */ 



/* Closes and tidies up everything that was used. */ 

/* */ 

/**********************************************************************/ 

VOID CloseAll ( VOID ) 

{ 

/* Close everything in the reverse order in which they were opened */ 

/* Close the Graphics Library */ 
if (GfxBase) 

CloseLibrary ((struct Library *) GfxBase) ; 

/* Close the Intuition Library */ 
if (IntuitionBase) 

CloseLibrary ((struct Library *) IntuitionBase) ; 
} 

/* */ 

/* VOID DestroyView (struct View *view) */ 

/* " */ 

/* Close and free everything to do with the View */ 

/* */ 

/**********************^ 

VOID DestroyView (struct View *view) 

{ 

struct ViewExtra *ve ; 
if (view) 

{ 

if (ve = (struct ViewExtra *) GfxLookUp (view) ) 

{ 

if (ve->Monitor) 

CloseMonitor (ve->Monitor) ; 

GfxFree ( (struct ExtendedNode *)ve); 
} 

/* Free up the copper lists */ 
if (view->LOFCprList) 

FreeCprList (view->LOFCprList) ; 

if (view->SHFCprList) 

FreeCprList (view->SHFCprList) ; 

FreeVec (view) ; 
} 
} 

/* */ 

/* struct View *DupView (struct View *v, ULONG ModelD) */ 

/* */ 

/* Duplicate the View. */ 

/* */ 

/**************************************** 

struct View *DupView (struct View *v, ULONG ModelD) 

{ 

/* Allocate and init a View structure. Also, get a ViewExtra 
* structure and attach the monitor type to the View. 
*/ 

struct View *view = NULL; 
struct ViewExtra *ve = NULL; 
struct MonitorSpec *mspc = NULL; 

if (view = AllocVec (sizeof (struct View), MEMF_PUBLIC | MEMF_CLEAR) ) 

{ 

if (ve = GfxNew(VIEW_EXTRA_TYPE) ) 

{ 



if (mspc = OpenMonitor (NULL, Mode ID ) ) 

{ 

InitView (view) ; 

view->DyOf f set = v->DyOf f set ; 

view->DxOf f set = v->DxOf f set ; 

view- >Mode s = v - >Mode s ; 

GfxAssociate (view, (struct ExtendedNode *)ve); 

ve->Monitor = mspc; 

} 

else printf ( "Could not open monitor\n" ) ; 

} 

else printf ( "Could not get ViewExtra\n" ) ; 

} 

else printf ( "Could not create View\n"); 

if (view && ve && mspc) 

return (view) ; 
else 

{ 

DestroyView (view) ; 

return (NULL) ; 
} 
} 

/* */ 

/* VOID DestroyViewPort (struct Viewport *vp) */ 

/* ' */ 

/* Close and free everything to do with the Viewport. */ 

/* */ 

/**********************^ 

VOID DestroyViewPort (struct ViewPort *vp) 

{ 

if (vp) 

{ 

/* Find the Viewport's ColorMap. From that use VideoControl 

* to get the ViewPortExtra, and free it. 

* Then free the ColorMap, and finally the Viewport itself. 

*/ 

struct ColorMap *cm = vp->ColorMap; 
struct Tagltem ti [] = 

{ 

{VTAG_VIEWPORTEXTRA_GET, NULL}, /* <-- This field will be filled in */ 
{VTAG_END_CM, NULL} 

}; 



if (cm) 
{ 



} 

else 

{ 



if (VideoControl (cm, ti) == NULL) 

GfxFree ( (struct ExtendedNode *) ti [0] . ti_Data) ; 
else 

printf ( "VideoControl error in DestroyViewPort () \n" ) ; 

FreeColorMap (cm) ; 



printf ( "Could not free the ColorMap\n" ) ; 



} 

FreeVPortCopLists (vp) ; 
FreeVec (vp) ; 



/* */ 

/* struct ViewPort *DupViewPort (struct ViewPort *vp, ULONG ModelD) */ 

/* */ 

/* Duplicate the Viewport. */ 



/* */ 

struct ViewPort *DupViewPort (struct Viewport *vp, ULONG ModelD) 

{ 

/* Allocate and initialise a Viewport. Copy the Viewport width and 

* heights, offsets, and modes values. Allocate and initialize a 

* ColorMap. 

* Also, allocate a ViewPortExtra, and copy the TextOScan values of the 

* ModelD from the database into the ViewPortExtra. 
*/ 

#define COLOURS 3 2 

struct Viewport *Myvp; 

struct ViewPortExtra *vpe; 

struct ColorMap *cm; 

struct Tagltem ti [] = /* to attach everything */ 

{ 

{VTAG_ATTACH_CM_SET, NULL}, /* these NULLS will be replaced in the code */ 
{VTAG_VIEWPORTEXTRA_SET, NULL}, 
{VTAG_NORMAL_DISP_SET, NULL}, 
{VTAG_END_CM, NULL} 

}; 

struct Dimensionlnf o query = {o}; 

UWORD colour; 

int c ; 

ULONG got info = NULL; 

if (Myvp = AllocVec (sizeof (struct ViewPort), MEMF_CLEAR | MEMF_PUBLIC) ) 

{ 

if (vpe = (struct ViewPortExtra *) GfxNew (VIEWPORT_EXTRA_TYPE) ) 

{ 

if (cm = GetColorMap(32) ) 

{ 

if (gotinfo = GetDisplaylnf oData (NULL, (APTR) &query, 

sizeof (query) , DTAG_DIMS, ModelD)) 

{ 

InitVPort (Myvp) ; 

/* duplicate the Viewport structure */ 
Myvp->DWidth = vp->DWidth; 
Myvp->DHeight = vp->DHeight; 
Myvp->DxOf f set = vp->DxOf f set ; 
Myvp->DyOf f set = vp->DyOf f set ; 
Myvp->Modes = vp->Modes; 

Myvp->SpritePriorities = vp->SpritePriorities; 
Myvp->ExtendedModes = vp->ExtendedModes ; 

/* duplicate the Overscan values */ 
vpe->DisplayClip = query .TxtOScan; 

/* attach everything together */ 

ti [0] . ti_Data = (ULONG)Myvp; 

ti [1] . ti_Data = (ULONG)vpe; 

ti [2] . ti_Data = (ULONG) FindDisplaylnfo (ModelD) ; 

if (VideoControl (cm, ti) != NULL) 

{ 

printf ( "VideoControl error in CreateViewPort ( ) \n" ) ; 

} 

/* copy the colours from the workbench */ 
for (c = 0; c < COLOURS; C++) 

{ 

if ((colour = GetRGB4 (vp->ColorMap, c) ) != -1) 

{ 

SetRGB4CM(cm, c, (colour >> 8), 

((colour >> 4) & Oxf ) , (colour & Oxf ) ) ; 
} 
} 
} 
else printf ( "Database error\n"); 



} 



else printf ( "Could not get the ColorMap\n" ) ; 

} 

else printf ( "Could not get the ViewPortExtra\n" ) ; 

} 

else printf ( "Could not get the Viewport \n" ) ; 

if (Myvp && vpe && cm && gotinfo) 

return (Myvp) ; 
else 

{ 

DestroyViewPort (vp) ; 

return (NULL) ; 
} 



/* */ 

/* VOID DestroyBitMap (struct BitMap *Mybm, SHORT width, SHORT height, SHORT depth) */ 

/* */ 

/* Close and free everything to do with the BitMap */ 

/* " */ 

/***********************************************************************************/ 

VOID DestroyBitMap (struct BitMap *Mybm, SHORT width, SHORT height, SHORT depth) 

{ 

int i ; 

if (Mybm) 

{ 

for (i = 0; (i < depth) ; i++) 

{ 

if (Mybm->Planes [i] ) 

FreeRaster (Mybm->Planes [i] , width, height); 

} 

FreeVec (Mybm) ; 

} 
} 

/* */ 

/* struct BitMap *CreateBitMap (SHORT width, SHORT height, SHORT depth) */ 

/* */ 

/* Create the BitMap. */ 

/* */ 

/***********************************************************************/ 

struct BitMap *CreateBitMap (SHORT width, SHORT height, SHORT depth) 

{ 

/* Allocate a BitMap structure, initialise it, and allocate each plane. */ 

struct BitMap *Mybm; 

PLANEPTR allocated = (PLANEPTR) 1; 

int i ; 

if (Mybm = AllocVec (sizeof (struct BitMap), MEMF_CLEAR | MEMF_PUBLIC) ) 

{ 

InitBitMap (Mybm, depth, width, height); 

for (i = 0; ((i < depth) && (allocated)); i++) 

allocated = (Mybm->Planes [i] = AllocRaster (width, height)); 

if (allocated == NULL) 

{ 

printf ( "Could not allocate all the planes\n"); 
DestroyBitMap (Mybm, width, height, depth); 
Mybm = NULL; 
} 
} 
else printf ( "Could not get BitMap\n"); 

return (Mybm) ; 



/* */ 

/* VOID ShowView (struct View *view, struct Viewport *vp, struct BitMap *bm, */ 

/* SHORT width, SHORT height) */ 

/* * / 

/* Assemble and display the View. */ 

/* " ' */ 

VOID ShowView (struct View *view, struct Viewport *vp, struct BitMap *bm, 

SHORT width, SHORT height) 

{ 

/* Attach the BitMap to the Viewport via a Raslnfo. Attach the Viewport 

* to the View. Clear the BitMap, and draw into it by attaching the BitMap 

* to a RastPort. Then MakeVPort ( ) , MrgCop ( ) and LoadView ( ) . 

* Just wait for the user to press <RETURN> before returning. 
*/ 

struct RastPort *rp; 
struct Raslnfo *ri; 

if (rp = AllocVec (sizeof (struct RastPort), MEMF_CLEAR | MEMF_PUBLIC) ) 

{ 

if (ri ■ AllocVec (sizeof (struct Raslnfo), MEMF_CLEAR | MEMF_PUBLIC) ) 

{ 

InitRastPort (rp) ; 
ri->BitMap = rp->BitMap = bm; 
vp->RasInfo = ri; 
view->ViewPort = vp; 

/* render */ 

SetRast(rp, 0); /* clear the background */ 

SetAPen(rp, ((1 << bm->Depth) - 1)); /* use the last pen */ 

Move ( rp , , ) ; 

Draw(rp, width, 0) ; 

Draw(rp, width, height); 

Draw(rp, 0, height); 

Draw(rp, 0, 0) ; 

/* display it */ 
MakeVPort (view, vp) ; 
MrgCop (view) ; 
LoadView (view) ; 

getchar ( ) ; 

/* bring back the system */ 
RethinkDisplay ( ) ; 

FreeVec (ri) ; 

} 

else printf ( "Could not get RasInfo\n"); 

FreeVec (rp) ; 

} 

else printf ( "Could not get RastPort \n" ) ; 

} 

/* */ 

/* VOID main (int argc, char *argv[]) */ 

/* */ 

/* Clone the Workbench View using Graphics Library calls. */ 

/* */ 

/********************************^ 

VOID main (int argc, char *argv[]) 

{ 

struct Screen *wb; 
struct View *Myview; 
struct Viewport *Myvp; 
struct BitMap *Mybm; 



ULONG Mode ID; 
ULONG IbaseLock; 

Init () ; /* to open the libraries */ 

/* To clone the Workbench using graphics calls involves duplicating 

* the Workbench Viewport, Viewport mode, and Intuition's View. 

* This also involves duplicating the DisplayClip for the overscan 

* value, the colours, and the View position. 

* When this is all done, the View, Viewport, ColorMap and BitMap 

* (and ViewPortExtra, ViewExtra and Raslnfo) all have to be linked 

* together, and the copperlists made to create the display. 
* 

* This is not as difficult as it sounds (trust me!) 
*/ 

/* First, lock the Workbench screen, so no changes can be made to it 

* while we are duplicating it. 
*/ 

if (wb = LockPubScreen ( "Workbench" ) ) 

{ 

/* Find the Workbench's ModelD. This is a 32 -bit number that 

* identifies the monitor type, and the display mode of that monitor. 

*/ 

ModelD = GetVPModelD (&wb->ViewPort) ; 

/* We need to duplicate Intuition's View structure, so lock IntuitionBase 

* to prevent the View changing under our feet . 

*/ 

IbaseLock = LocklBase (0) ; 

if (Myview = DupView (&IntuitionBase->ViewLord, ModelD)) 

{ 

/* The View has been cloned, so we don't need to keep it locked. */ 
UnlocklBase (IbaseLock) ; 

/* Now duplicate the Workbench's Viewport. Remember, we still have 
* the Workbench locked. 

*/ 

if (Myvp = DupViewPort (&wb->ViewPort , ModelD)) 

{ 

/* Create a BitMap to render into. This will be of the 
* same dimensions as the Workbench. 

*/ 

if (Mybm = CreateBitMap (wb->Width, wb->Height, wb- >BitMap. Depth) ) 

{ 

/* Now we have everything copied, show something */ 
ShowView (Myview, Myvp, Mybm, wb->Width-l, wb->Height-l) ; 

/* Now free up everything we have allocated */ 
DestroyBitMap (Mybm, wb->Width, wb->Height, wb- >BitMap. Depth) ; 

} 

DestroyViewPort (Myvp) ; 

} 

DestroyView (Myview) ; 

} 
else 

{ 

UnlocklBase (IbaseLock) ; 

} 

UnlockPubScreen(NULL, wb) ; 

} 

CloseAll () ; 

} 
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Advanced Topics 

This section covers advanced display topics such as dual-playfield mode, double-buffering, EHB mode and HAM 



mode. 

Creating a Dual-Playfield Display 

In dual-playfield mode, you have two separately controllable playfields. You specify dual-playfield mode in 1.3 by 
setting the DUALPF bit in the ViewPort.Modes field. In Release 2, you specify dual-playfield by using any 
ModelD that includes DPF in its name as listed in <graphics/displayinfo.h>. 

In dual-playfield mode, you always define two Raslnfo data structures. Each of these structures defines one of 
the playfields. There are five different ways you can configure a dual-playfield display, because there are five 
different distributions of the bitplanes which the system hardware allows. 

Table 27-6: Bitplane Assignment in Dual-playfield Mode 
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Under 1 .3 if PFBA is set in the ViewPort.Modes field, or, under Release 2, if the ModelD includes DPF2 in its 
name, then the playfield priorities are swapped and playfield 2 will be displayed in front of playfield 1 . In this way, 
you can get more bitplanes in the background playfield than you have in the foreground playfield. The playfield 
priority affects only one ViewPort at a time. If you have multiple Viewports with dual-playfields, the playfield 
priority is set for each one individually. 

Here's a summary of the steps you need to take to create a dual-playfield display: 

Allocate one View structure and one ViewPort structure. 

Allocate two BitMap structures. Allocate two Raslnfo structures (linked together), each pointing to a 
separate BitMap. The two Raslnfo structures are linked together as follows: 

struct Raslnfo playfieldl, playfield2; 
playf ieldl .Next = &playf ield2 ; 
playfield2 .Next = NULL; 

Initialize each BitMap structure to describe one playfield, using one of the permissible bitplane 
distributions shown in the above table and allocate memory for the bitplanes themselves. Note that 
BitMap 1 and BitMap 2 need not be the same width and height. 

Initialize the ViewPort structure. In 1 .3, specify dual-playfield mode by setting the DUALPF bit (and 
PFBA, if appropriate) in the ViewPort.Modes field. Under Release 2, specify dual-playfield mode by 
selecting a ModelD that includes DPF (or DPF2) in its name as listed in <graphics/displayinfo.h>. Set 
the ViewPort.Raslnfo field to the address of the playfield 1 Raslnfo. 
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Set up the ColorMap information 

Call MakeVPort(), MrgCop() and LoadView() to display the newly created ViewPort. 

For display purposes, each of the two BitMaps is assigned to a separate ViewPort. To draw separately into the 
BitMaps, you must also assign these BitMaps to two separate RastPorts. The section called "Initializing a 
RastPort Structure" shows you how to use a RastPort data structure to control your drawing routines. 

Creating a Double-Buffered Display 

To produce smooth animation or similar effects, it is occasionally necessary to double-buffer your display. To 
prevent the user from seeing your graphics rendering while it is in progress, you will want to draw into one 
memory area while actually displaying a different area. 

There are two methods of creating and displaying a double-buffered display. The simplest method is to create 



two complete Views and switch back and forth between them with LoadView() and WaitTOF(). 

The second method consists of creating two separate display areas and two sets of pointers to those areas for a 
single View. This is more complicated but takes less memory. 

Allocate one ViewPort structure and one View structure. 

Allocate two BitMap structures and one Raslnfo structure. Initialize each BitMap structure to describe 
one drawing area and allocate memory for the bitplanes themselves. Initialize the Raslnfo structure, 
setting the Raslnfo. BitMap field to the address of one of the two BitMaps you created. 

Call MakeVPort(), MrgCopQ and LoadViewQ. When you call MrgCop(), the system uses the 
information you have provided to create a Copper instruction list for the Copper to execute. The system 
allocates memory for a long-frame (LOF) Copper list and, if this is an interlaced display, a short-frame 
(SHF) Copper list as well. The system places a pointer to the long-frame Copper list in View.LOFCprList 
and a pointer to a short-frame Copper list (if this is an interlaced display) in View.SHFCprList. The 
Copper instruction stream referenced by these pointers applies to the first BitMap. 

Save the values in View.LOFCprList and View.SHFCprlist and reset these fields to zero. Place a 
pointer to the second BitMap structure in the Raslnfo. BitMap field. Next call MakeVPortQ and 
MrgCop(). 

When you perform MrgCopO with the Copper instruction list fields of the View set to zero, the system 
automatically allocates and fills in a new list of instructions for the Copper. Now you have created two 
sets of instruction streams for the Copper, one that works with data in the first BitMap and the other that 
works with data in the second BitMap. 

You can save pointers to the second list of Copper instructions as well. Then, to perform the 
double-buffering, alternate between the two Copper lists. The code for the double-buffering loop would 
be as follows: call WaitTOF(), change the Copper instruction list pointers in the View, call LoadView() to 
show one of the BitMaps while drawing into the other BitMap, and repeat. 

Remember that you will have to call FreeCprList() on both sets of Copper lists when you have finished. 
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Extra-Half-Brite Mode 

In the Extra-Half-Brite mode you can create a single-playfield, low-resolution display with up to 64 colors, double 
the normal maximum of 32. This requires your ViewPort to be defined with six bitplanes. Under 1 .3, you specify 
EHB mode by setting the EXTRAJHALFBRITE bit in the ViewPort.Modes field. Under Release 2, you specify 
EHB by selecting any ModelD which includes EXTRAHALFBRITE in its name as defined in the include file 
< graphics/displainfo. h> . 

When setting up the color palette for an EHB display, you only specify values for registers to 31 . If you draw 
using color numbers through 31 , the pixel you draw will be the color specified in that particular system color 
register. If you draw using a color number from 32 to 63, then the color displayed will be half the intensity value of 
the corresponding color register from to 31 . For example, if color register is set to OxFFF (white), then color 
number 32 would be half this value or 0x777 (grey). 

EHB mode uses all six bitplanes. The color register (0 through 31) is obtained from the bit combinations from 
planes 5 to 1 , in that order of significance. Plane 6 is used to determine whether the full intensity (bit value 0) 
color or half-intensity (bit value 1) color is to be displayed. 

Hold-And-Modify Mode 

In hold-and-modify mode you can create a single-playfield, low-resolution display in which 4,096 different colors 
can be displayed simultaneously. This requires your ViewPort to be defined with six bitplanes. Under 1 .3, you 
specify HAM mode by setting the HAM flag in the ViewPort.Modes field. Under Release 2, you specify HAM by 
selecting any ModelD which includes HAM in its name as defined in <graphics/displayinfo.h>. 

When you draw into the BitMap associated with this ViewPort, you can choose colors in one of four different 
ways. If you draw using color numbers to 15, the pixel you draw will appear in the color specified in that 
particular system color register. If you draw with any other color value (1 6 to 63) the color displayed depends on 



the color of the pixel that is to the immediate left of this pixel on the screen. To see how this works, consider how 
the bitplanes are used in HAM. 



Hold-and-modify mode requires six bitplanes. 
through 4 are treated, as follows: 



Planes 5 and 6 are used to modify the way bits from planes 1 



If the bit combination from planes 6 and 5 for any given pixel is 00, normal color selection procedure is 
followed. Thus, the bit combinations from planes 4 to 1 , in that order of significance, are used to choose 
one of 16 color registers (registers through 15). 

If the bit combination in planes 6 and 5 is 01 , the color of the pixel immediately to the left of this pixel is 
duplicated and then modified. The bit combinations from planes 4 through 1 are used to replace the four 
bits representing the blue value of the preceding pixel color. (No color registers are changed.) 

If the bit combination in planes 6 and 5 is 1 0, then the color of the pixel immediately to the left of this 
pixel is duplicated and modified. The bit combinations from planes 4 through 1 are used to replace the 
four bits representing the red value of the preceding pixel color. 

If the bit combination in planes 6 and 5 is 1 1 , then the color of the pixel immediately to the left of this 
pixel is duplicated and modified. The bit combinations from planes 4 through 1 are used to replace the 
four bits representing the green value of the preceding pixel color. 
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You can use just five bitplanes in HAM mode. In that case, the data for the sixth plane is automatically assumed 
to be 0. Note that for the first pixel in each line, hold-and-modify begins with the background color. The color 
choice does not carry over from the preceding line. 

Note: Since a typical hold-and-modify pixel only changes one of the three RGB color values at 
a time, color selection is limited. HAM mode does allow for the display of 4,096 colors 
simultaneously, but there are only 64 color options for any given pixel (not 4,096). The color 
of a pixel depends on the color of the preceding pixel. 



Drawing Routines 



Most of the graphics drawing routines require information about how the drawing is to take place. For this reason, 
most graphics drawing routines use a data structure called a RastPort, that contains pointers to the drawing area 
and drawing variables such as the current pen color and font to use. In general, you pass a pointer to your 
RastPort structure as an argument whenever you call a drawing function. 

The RastPort Structure 

The RastPort data structure can be found in the include files <graphics/rastport.h> and <graphics/rastport.i>. It 
contains the following information: 

struct RastPort 



struct Layer * Layer; 
struct BitMap *BitMap; 
UWORD *AreaPtrn; 
struct TmpRas *TmpRas; 
struct Arealnfo *AreaInf ob- 
struct Gelslnfo *GelsInfo; 
UBYTE Mask; 
BYTE FgPen; 
BYTE BgPen; 
BYTE AOlPen; 
BYTE DrawMode ; 
BYTE AreaPtSz; 
BYTE linpatcnt; 
BYTE dummy ; UWORD 
UWORD LinePtrn; 
WORD cp_x , cp_y ; 



/* Ptr to areafill pattern */ 



/* Write mask for this raster */ 
/* Foreground pen for this raster */ 
/* Background pen */ 
/* Areafill outline pen */ 

/* Drawing mode for fill, lines, and text */ 
/* 2*n words for areafill pattern */ 
/* Current line drawing pattern preshift */ 
Flags; /* Miscellaneous control bits */ 

/* 16 bits for textured lines */ 
/* Current pen position */ 



UBYTE 


minterms [8] ; 




WORD 


PenWidth; 




WORD 


PenHeight ; 




struct 


TextFont *Font; 


/ 


UBYTE 


AlgoStyle; 


/ 


UBYTE 


TxFlags; 


/ 


UWORD 


TxHeight ; 


/ 


UWORD 


TxWidth; 


/ 


UWORD 


TxBaseline; 


/ 


WORD 


TxSpacing; 


/ 


APTR 


*RP User; 




ULONG 


longreserved [2] ; 




#ifndef GFX 


_RASTP0RT_1_2 




UWORD 


wordreserved [7] ; 


/ 


UBYTE 


reserved [8] ; 


/ 


#endif 

}; 







Current font address */ 

The algorithmically generated style */ 

Text specific flags */ 

Text height */ 

Text nominal width */ 

Text baseline */ 

Text spacing (per character) */ 



/* Used to be a node */ 
For future use */ 



The sections that follow explain each of the items in the RastPort structure is used. 
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Initializing a BitMap Structure 



Associated with the RastPort is another data structure called a BitMap which contains a description of the 
organization of the data in the drawing area. This tells the graphics library where in memory the drawing area is 
located and how it is arranged. Before you can set up a RastPort for drawing you must first declare and initialize 
a BitMap structure, defining the characteristics of the drawing area, as shown in the following example. This was 
already shown in the "Forming a Basic Display" section, but it is repeated here because it relates to drawing as 
well as to display routines. (You need not necessarily use the same BitMap for both the drawing and the display, 
e.g., double-buffered displays.) 



#define DEPTH 2 
#define WIDTH 320 
#define HEIGHT 200 



/* Two planes deep. */ 
/* Width in pixels. */ 
/* Height in scanlines. */ 



struct BitMap bitMap; 

/* Initialize the BitMap. */ 

InitBitMap (kbitMap, DEPTH, WIDTH, HEIGHT); 

Initialising a RastPort Structure 

Once you have a BitMap set up, you can declare and initialize the RastPort and then link the BitMap into it. 
Here is a sample initialization sequence: 

struct BitMap bitMap = {Ob- 
struct RastPort rastPort = {o}; 

/* Initialize the RastPort and link the BitMap to it. */ 
InitRastPort (krastPort) ; 
rastPort .BitMap = &bitMap; 

Initialize, Then Link. You cannot link the bitmap in until after the RastPort has been 
initialized. 

RastPort Area-fill Information 

Two structures in the RastPort -- Arealnfo and TmpRas -- define certain information for area filling operations. 
The Arealnfo pointer is initialized by a call to the routine lnitArea(). 

#define AREA SIZE 200 



register USHORT i ; 



WORD areaBuffer [AREA_SIZE] ; 
struct Arealnfo arealnfo = {o}; 

/* Clear areaBuffer before calling InitAreaO . */ 
for (i=0; i<AREA_SIZE; i++) 
areaBuf f er [i] = 0; 

InitArea (karealnfo, areaBuffer, (AREA_SIZE*2) /5) ; 

The area buffer must start on a word boundary. That is why the sample declaration shows areaBuffer as 
composed of unsigned words (200), rather than unsigned bytes (400). It still reserves the same amount of space, 
but aligns the data space correctly. 

To use area fill, you must first provide a work space in memory for the system to store the list of points that define 
your area. You must allow a storage space of 5 bytes per vertex. To create the areas in the work space, you use 
the functions AreaMove(), AreaDraw(), and AreaEnd(). 
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Typically, you prepare the RastPort for area-filling by following the steps in the code fragment above and then 
linking your Arealnfo into the RastPort like so: 

rastPort->AreaInf o = karealnfo; 

In addition to the Arealnfo structure in the RastPort, you must also provide the system with some work space to 
build the object whose vertices you are going to define. This requires that you initialize a TmpRas structure, then 
point to that structure for your RastPort to use. 

Here is a code fragment that builds and initialises a TmpRas. First the TmpRas structure is initialized (via 
InitTmpRasQ) then it is linked into the RastPort structure. 

Allocate Enough Space. The area to which TmpRas.RasPtr points must be at least as large 
as the area (width times height) of the largest rectangular region you plan to fill. Typically, you 
allocate a space as large as a single bitplane (usually 320 by 200 bits for Lores mode, 640 by 
200 for Hires, and 1280 by 200 for SuperHires). 

When you use functions that dynamically allocate memory from the system, you must remember to return these 
memory blocks to the system before your program exits. See the description of FreeRaster() in the Amiga ROM 
Kernel Reference Manual: Includes and Autodocs. 

RastPort Graphics Element Pointer 

The graphics element pointer in the RastPort structure is called Gelslnfo. If you are doing graphics animation 
using the GELS system, this pointer must refer to a properly initialized Gelslnfo structure. See the chapter on 
"Graphics Sprites, Bobs and Animation" for more information. 

RastPort Write Mask 

The write mask is a RastPort variable that determines which of the bitplanes are currently writable. For most 
applications, this variable is set to all bits on. This means that all bitplanes defined in the BitMap are affected by 
a graphics writing operation. You can selectively disable one or more bitplanes by simply specifying a bit in that 
specific position in the control byte. For example: 

#include <graphics/gfxmacros .h> 

SetWrMsk (krastPort, OxFB) ; /* disable bitplane 2 */ 

A useful application for the Mask field is to set or clear plane 6 while in the Extra-Half-Brite display mode to create 
shadow effects. For example: 

SetWrMsk (krastPort, OxEO) ; /* Disable planes 1 through 5. */ 

SetAPen (&rastPort, 0); /* Clear the Extra-Half-Brite bit */ 

RectFill (krastPort, 20, 20, 40, 30); /* in the old rectangle. */ 



SetAPen(&rastPort, 32) ; /* Set the Extra-Half -Brite bit */ 

RectFill (krastPort, 30, 25, 50, 35); /* in the new rectangle. */ 

SetWrMsk(&rastPort, -1); /* Re-enable all planes. */ 

Graphic Primitives 583 

RastPort Drawing Pens 

The Amiga has three different drawing "pens" associated with the graphics drawing routines. These are: 

FgPen--the foreground or primary drawing pen. For historical reasons, it is also called the A-Pen. 

BgPen--the background or secondary drawing pen. For historical reasons, it is also called the B-Pen. 

AOIPen-the area outline pen. For historical reasons, it is also called the O-Pen. 

A drawing pen variable in the RastPort contains the current value (range 0-255) for a particular color choice. 
This value represents a color register number whose contents are to be used in rendering a particular type of 
image. The effect of the pen value is dependent upon the drawing mode and can be influenced by the pattern 
variables and the write mask as described below. Always use the system calls (e.g. SetAPen()) to set the 
different pens, never store values directly into the pen fields of the RastPort. 

Colors Repeat Beyond 31. The Amiga 500/2000/3000 (with original chips or ECS) contains 
only 32 color registers. Any range beyond that repeats the colors in 0-31 . For example, pen 
numbers 32-63 refer to the colors in registers 0-31 (except when you are using 
Extra-Half-Brite mode). 

The graphics library drawing routines support BitMaps up to eight planes deep allowing for future expansion of 
the Amiga hardware. 

The color in FgPen is used as the primary drawing color for rendering lines and areas. This pen is used when the 
drawing mode is JAM1 (see the next section for drawing modes). JAM1 specifies that only one color is to be 
"jammed" into the drawing area. 

You establish the color for FgPen using the statement: 

SetAPen (krastPort , newcolor); 

The color in BgPen is used as the secondary drawing color for rendering lines and areas. If you specify that the 
drawing mode is JAM2 (jamming two colors) and a pattern is being drawn, the primary drawing color (FgPen) is 
used where there are 1s in the pattern. The secondary drawing color (BgPen) is used where there are 0s in the 
pattern. 

You establish the drawing color for BgPen using the statement: 

SetBPen (&rastPort , newcolor); 

The area outline pen AOIPen is used in two applications: area fill and flood fill. (See "Area Fill Operations" below.) 
In area fill, you can specify that an area, once filled, can be outlined in this AOIPen color. In flood fill (in one of its 
operating modes) you can fill until the flood-filler hits a pixel of the color specified in this pen variable. 

You establish the drawing color for AOIPen using the statement: 

SetOPen (krastPort , newcolor); 
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RastPort Drawing Modes 

Four drawing modes may be specified in the RastPort. DrawMode field: 



JAM1 

Whenever you execute a graphics drawing command, one color is jammed into the target drawing 
area. You use only the primary drawing pen color, and for each pixel drawn, you replace the color at 
that location with the FgPen color. 

JAM2 

Whenever you execute a graphics drawing command, two colors are jammed into the target drawing 
area. This mode tells the system that the pattern variables (both line pattern and area pattern-see 
the next section) are to be used for the drawing. Wherever there is a 1 bit in the pattern variable, the 
FgPen color replaces the color of the pixel at the drawing position. Wherever there is a bit in the 
pattern variable, the BgPen color is used. 

COMPLEMENT 

For each 1 bit in the pattern, the corresponding bit in the target area is complemented-that is, its state 
is reversed. As with all other drawing modes, the write mask can be used to protect specific bitplanes 
from being modified. Complement mode is often used for drawing and then erasing lines. 

INVERSVID 

This is the drawing mode used primarily for text. If the drawing mode is (JAM1 | INVERSVID), the text 
appears as a transparent letter surrounded by the FgPen color. If the drawing mode is 
(JAM2|INVERSVID), the text appears as in (JAM1 1 INVERSVID) except that the BgPen color is used to 
draw the text character itself. In this mode, the roles of FgPen and BgPen are effectively reversed. 

You set the drawing modes using the statement: 

SetDrMd (&rastPort , newmode); 

Set the newmode argument to one of the four drawing modes listed above. 

RastPort Line and Area Drawing Patterns 

The RastPort data structure provides two different pattern variables that it uses during the various drawing 
functions: a line pattern and an area pattern. The line pattern is 16 bits wide and is applied to all lines. When you 
initialize a RastPort, this line pattern value is set to all 1s (hex FFFF), so that solid lines are drawn. You can also 
set this pattern to other values to draw dotted lines if you wish. For example, you can establish a dotted line 
pattern with the graphics macro SetDrPt(): 

SetDrPt (krastPort, OxCCCC) ; 

The second argument is a bit-pattern, 1 1 001 1 001 1 001 1 00, to be applied to all lines drawn. If you draw multiple, 
connected lines, the pattern cleanly connects all the points. 

The area pattern is also 16 bits wide and its height is some power of two. This means that you can define patterns 
in heights of 1 , 2, 4, 8, 1 6, and so on. To tell the system how large a pattern you are providing, use the graphics 
macro SetAfPt(): 

SetAf Pt (krastPort , &areaPattern, power_of_two) ; 
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The &areaPattern argument is the address of the first word of the area pattern and power_of_two specifies how 
many words are in the pattern. For example: 

USHORT ditherData [] = 

{ 

0x5555, OxAAAA 

}; 

SetAf Pt (krastPort, ditherData, 1) ; 

This example produces a small cross-hatch pattern, useful for shading. Because power_of_two is set to 1 , the 
pattern height is 2 to the 1st, or 2 rows high. 

To clear the area fill pattern, use: 



SetAfPt (krastPort, NULL, 0); 

Pattern Positioning. The pattern is always positioned with respect to the upper left corner of 
the RastPort drawing area (the 0,0 coordinate). If you draw two rectangles whose edges are 
adjacent, the pattern will be continuous across the rectangle boundaries. 

The last example given produces a two-color pattern with one color where there are 1s and the other color where 
there are 0s in the pattern. A special mode allows you to develop a pattern having up to 256 colors. To create 
this effect, specify power_of_two as a negative value instead of a positive value. For instance, the following 
initialization establishes an 8-color checkerboard pattern where each square in the checkerboard has a different 
color. 

USHORT areaPattern[3] [8] = 
{ 



plane 
{ 


pattern 


*/ 


0x0000, 


0x0000, 




Oxffff , 


Oxffff, 




0x0000, 


0x0000, 




Oxffff, 


Oxffff 


}. 






plane 


1 pattern 


*/ 


{ 








0x0000, 


0x0000, 




0x0000, 


0x0000, 




Oxffff, 


Oxffff, 




Oxffff, 


Oxffff 


}. 






plane 


2 pattern 


*/ 


{ 








OxffOO, 


OxffOO, 




OxffOO, 


OxffOO, 




OxffOO, 


OxffOO, 




OxffOO, 


OxffOO 



}; 

SetAf Pt (krastPort, kareaPattern, -3); 

/* when doing this, it is best to set */ 
/* three other parameters as follows: */ 
SetAPen(&rastPort, -1); 
SetBPen(&rastPort, 0) ; 
SetDrMdt&rastPort, JAM2) ; 

If you use this multicolored pattern mode, you must provide as many planes of pattern data as there are planes in 
your BitMap. 
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RastPort Pen Position and Size 

The graphics drawing routines keep the current position of the drawing pen in the RastPort fields cp_x and cp_y, 
for the horizontal and vertical positions, respectively. The coordinate location 0,0 is in the upper left corner of the 
drawing area. The x value increases proceeding to the right; the y value increases proceeding toward the bottom 
of the drawing area. 

The variables RastPort.PenWidth and RastPort.PenHeight are not currently implemented. These fields should 
not be read or written by applications. 

Text Attributes 

Text attributes and font information are stored in the RastPort fields Font, AlgoStyle, TxFlags, TxHeight, 



TxWidth, TxBaseline and TxSpacing. These are normally set by calls to the graphics font routines which are 
covered separately in the chapter on "Graphics Library and Text. 

Using the Graphics Drawing Routines 

This section shows you how to use the Amiga drawing routines. All of these routines work either on their own or 
along with the windowing system and layers library. For details about using the layers and windows, see the 
chapters on "Layers Library" and "Intuition Windows". 

Use WaitBlitQ. The graphics library rendering and data movement routines generally wait to 
get access to the blitter, start their blit, and then exit. Therefore, you must WaitBlit() after a 
graphics rendering or data movement call if you intend to immediately deallocate, examine, or 
perform order-dependent processor operations on the memory used in the call. 

As you read this section, keep in mind that to use the drawing routines, you need to pass them a pointer to a 
RastPort. You can define the RastPort directly, as shown in the sample program segments in preceding 
sections, or you can get a RastPort from your Window structure using code like the following: 

struct Window *window; 
struct RastPort *rastPort; 

window = OpenWindow (&newWindow) ; /* You could use OpenWindowTags ( ) */ 
if (window) 

rastPort = window- >RPort; 

You can also get the RastPort from the Layer structure, if you are not using Intuition. 

Drawing Individual Pixels 

You can set a specific pixel to a desired color by using a statement like this: 

SHORT x, y; 

LONG result; 

result = WritePixel (&rastPort , x, y) ; 

WritePixel() uses the primary drawing pen and changes the pixel at that x,y position to the desired color if the x,y 
coordinate falls within the boundaries of the RastPort. A value of is returned if the write was successful; a value 
of -1 is returned if x,y was outside the range of the RastPort. 
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Reading Individual Pixels 

You can determine the color of a specific pixel with a statement like this: 

SHORT x, y; 

LONG result; 

result = ReadPixel (krastPort , x, y) ; 

ReadPixel() returns the value of the pixel color selector at the specified x,y location. If the coordinates you specify 
are outside the range of your RastPort, this function returns a value of -1 . 

Drawing Elipses and Circles 

Two functions are associated with drawing ellipses: DrawCircle() and DrawEllipseQ. DrawCircle(), a macro that 
calls DrawEllipseQ, will draw a circle from the specified center point using the specified radius. This function is 
executed by the statement: 

DrawCircle (&rastPort , center_x, center_y, radius); 

Similarly, DrawEllipse() draws an ellipse with the specified radii from the specified center point: 

DrawEllipse (krastPort , center_x, center_y, horiz_r, vert_r) ; 



Neither function performs clipping on a non-layered RastPort. 

Drawing a Line 

Two functions are associated with line drawing: Move() and Draw(). Move() simply moves the cursor to a new 
position. It is like picking up a drawing pen and placing it at a new location. This function is executed by the 
statement: 

Move (krastPort , x, y) ; 

DrawQ draws a line from the current x,y position to a new x,y position specified in the statement itself. The 
drawing pen is left at the new position. This is done by the statement: 

DrawfSrastPort, x, y) ; 

Draw() uses the pen color specified for FgPen. Here is a sample sequence that draws a line from location (0,0) to 
(100,50). 

SetAPen( krastPort, COLOR1) ; /* Set A pen color. */ 
Move (krastPort , 0, 0); /* Move to this location. */ 
Draw (krastPort , 100,50); /* Draw to a this location. */ 

Caution: If you attempt to draw a line outside the bounds of the BitMap, using the basic 
initialized RastPort, you may crash the system. You must either do your own software 
clipping to assure that the line is in range, or use the layers library. Software clipping means 
that you need to determine if the line will fall outside your BitMap before you draw it, and 
render only the part which falls inside the BitMap. 
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Drawing Patterned Lines 

To turn the example above into a patterned line draw, simply set a drawing pattern, such as: 

SetDrPt (krastPort, OxAAAA) ; 

Now all lines drawn appear as dotted lines (OxAAAA = 1010101010101010 in binary). To resume drawing solid 
lines, execute the statement: 

SetDrPt (krastPort, ~0) ; 

Because ~0 is defined as all bits on (11...11) in binary. 

Drawing Multiply Lines with a Single Command 

You can use multiple Draw() statements to draw connected line figures. If the shapes are all definable as 
interconnected, continuous lines, you can use a simpler function, called PolyDrawQ. PolyDraw() takes a set of 
line endpoints and draws a shape using these points. You call PolyDraw() with the statement: 

PolyDraw (krastPort , count, arraypointer) ; 

PolyDrawQ reads the array of points and draws a line from the first pair of coordinates to the second, then a 
connecting line to each succeeding pair in the array until count points have been connected. This function uses 
the current drawing mode, pens, line pattern, and write mask specified in the target RastPort; for example, this 
fragment draws a rectangle, using the five defined pairs of x,y coordinates. 

SHORT linearray[] = 

{ 

3, 3, 
15, 3, 
15, 15, 

3,15, 

3, 3 

}; 



PolyDraw (&rastPort , 5, linearray) ; 

Area-Fill Operations 

Assuming that you have properly initialized your RastPort structure to include a properly initialized Arealnfo, you 
can perform area fill by using the functions described in this section. 

AreaMove() tells the system to begin a new polygon, closing off any other polygon that may already be in process 
by connecting the end-point of the previous polygon to its starting point. AreaMove() is executed with the 
statement: 

LONG result; 

result = AreaMove (&rastPort , x, y) ; 

AreaMove() returns if successful, -1 if there was no more space left in the vector list. AreaDraw() tells the 
system to add a new vertex to a list that it is building. No drawing takes place until AreaEnd() is executed. 
AreaDraw is executed with the statement: 

LONG result; 
result = AreaDraw (&rastPort, x, y) ; 
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AreaDraw() returns if successful, -1 if there was no more space left in the vector list. AreaEnd() tells the 
system to draw all of the defined shapes and fill them. When this function is executed, it obeys the drawing mode 
and uses the line pattern and area pattern specified in your RastPort to render the objects you have defined. 

To fill an area, you do not have to AreaDraw() back to the first point before calling AreaEnd(). AreaEnd() 
automatically closes the polygon. AreaEnd() is executed with the following statement: 

LONG result; 

result = AreaEnd (&rastPort) ; 

AreaEnd() returns if successful, -1 if there was an error. To turn off the outline function, you have to set the 
RastPort Flags variable back to with BNDRYOFF(): 

#include "graphics/gf xmacros . h" 
BNDRYOFF(&rastPort) ; 

Otherwise, every subsequent area-fill or rectangle-fill operation will outline their rendering with the outline pen 
(AOIPen). 

Ellipse and Circle-fill Operators 

Two functions are associated with drawing filled ellipses: AreaCircle() and AreaEllipseQ. AreaCircle() (a macro 
that calls AreaEllipse()) will draw a circle from the specified center point using the specified radius. This function 
is executed by the statement: 

AreaCircle (krastPort , center_x, center_y, radius); 
Similarly, AreaEllipse() draws a filled ellipse with the specified radii from the specified center point: 

AreaEllipse (krastPort , center_x, center_y, horiz_r, vert_r) ; 

Outlining with SetOPen() is not currently supported by the AreaCircle() and AreaEllipse() routines. 

Caution: If you attempt to fill an area outside the bounds of the BitMap, using the basic 
initialized RastPort, it may crash the system. You must either do your own software clipping 
to assure that the area is in range, or use the layers library. 

Flood-fill Operations 

Flood fill is a technique for filling an arbitrary shape with a color. The Amiga flood-fill routines can use a plain color 
or do the fill using a combination of the drawing mode, FgPen, BgPen and the area pattern. 



Flood-fill requires a TmpRas structure at least as large as the RastPort in which the flood-fill will be done. This is 
to ensure that even if the flood-filling operation "leaks", it will not flow outside the TmpRas and corrupt another 
task's memory. 

You use the Flood() routine for flood fill. The syntax for this routine is as follows: 

Flood (krastPort , mode, x, y) ; 
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The rastPort argument specifies the RastPort you want to draw into. The x and y arguments specify the starting 
coordinate within the BitMap. The mode argument tells how to do the fill. There are two different modes for 
flood fill: 

Outline Mode 

In outline mode, you specify an x,y coordinate, and from that point the system searches outward in all 
directions for a pixel whose color is the same as that specified in the area outline pen (AOIPen). All 
horizontally or vertically adjacent pixels not of that color are filled with a colored pattern or plain color. 
The fill stops at the outline color. Outline mode is selected when the mode argument to Flood() is set 
toaO. 

Color Mode 

In color mode, you specify an x,y coordinate, and whatever pixel color is found at that position defines 
the area to be filled. The system searches for all horizontally or vertically adjacent pixels whose color is 
the same as this one and replaces them with the colored pattern or plain color. Color mode is selected 
when the mode argument ot Flood() is set to a one. 

The following sample program fragment creates and then flood-fills a triangular region. The overall effect is 
exactly the same as shown in the preceding area-fill example above, except that flood-fill is slightly slower than 
area-fill. Mode (fill to a pixel that has the color of the outline pen) is used in the example. 

BYTE oldAPen; 

UWORD oldDrPt; 

struct RastPort *rastPort = Window- >RPort ; 

/* Save the old values of the foreground pen and draw pattern. */ 
oldAPen = rastPort ->FgPen; 
oldDrPt = rastPort->LinePtrn; 

/* Use AreaOutline pen color for foreground pen. */ 

SetAPen( rastPort, rastPort ->A01Pen) ; 

SetDrPt (rastPort , ~0) ; /* Insure a solid draw pattern. */ 

Move (rastPort , 0, 0) ; /* Using mode to create a triangular shape */ 

Draw (rastPort, 0, 100); 

Draw (rastPort, 100, 100); 

Draw (rastPort , 0, 0); /* close it */ 

SetAPen (rastPort , oldAPen); /* Restore original foreground pen. */ 
Flood (rastPort, 0, 10, 50); /* Start Flood ( ) inside triangle. */ 

SetDrPt (rastPort , oldDrPt) ; /* Restore original draw mode. */ 

This example saves the current FgPen value and draws the shape in the same color as AOIPen. Then FgPen is 
restored to its original color so that FgPen, BgPen, DrawMode, and AreaPtrn can be used to define the fill within 
the outline. 

Rectangle-Fill Operators 

The final fill function, RectFill(), is for filling rectangular areas. The form of this function follows: 

RectFill (&rastPort , xmin, ymin, xmax, ymax); 

As usual, the rastPort argument specifies the RastPort you want to draw into. The xmin and ymin arguments 
specify the upper left corner of the rectangle to be filled. The xmax and ymax arguments specify the lower right 
corner of the rectangle to be filled. Note that the variable xmax must be equal to or greater than xmin, and ymax 



must be equal to or greater than ymin. 
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Rectangle-fill uses FgPen, BgPen, AOIPen, DrawMode, AreaPtrn and Mask to fill the area you specify. 
Remember that the fill can be multicolored as well as single- or two-colored. When the DrawMode is 
COMPLEMENT, it complements all bit planes, rather than only those planes in which the foreground is non-zero. 

Performing Data Move Operations 

The graphics library includes several routines that use the hardware blitterto handle the rectangularly organized 
data that you work with when doing raster-based graphics. These blitter routines do the following: 

Clear an entire segment of memory 

Set a raster to a specific color 

Scroll a subrectangle of a raster 

Draw a pattern "through a stencil" 

Extract a pattern from a bit-packed array and draw it into a raster 

Copy rectangular regions from one bitmap to another 

Control and utilize the hardware-based data mover, the blitter 

The following sections cover these routines in detail. 

WARNING: The graphics library rendering and data movement routines generally wait to get 
access to the blitter, start their blit, and then exit without waiting for the blit to finish. 
Therefore, you must WaitBlit() after a graphics rendering or data movement call if you 
intend to immediately deallocate, examine, or perform order-dependent processor operations 
on the memory used in the call. 

Clearing a Memory Area 

For memory that is accessible to the blitter (that is, internal Chip memory), the most efficient way to clear a range 
of memory is to use the blitter. You use the blitter to clear a block of memory with the statement: 

BltClear (memblock, bytecount, flags); 

The memblock argument is a pointer to the location of the first byte to be cleared and bytecount is the number 
of bytes to set to zero. In general the flags variable should be set to one to wait for the blitter operation to 
complete. Refer to the Amiga ROM Kernel Manual: Includes and Autodocs for other details about the flag 
argument. 
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Setting a Whole Raster to a Color 

You can preset a whole raster to a single color by using the function SetRast(). A call to this function takes the 
following form: 

SetRast (&rastPort , pen); 

As always, the &rastPort is a pointer to the RastPort you wish to use. Set the pen argument to the color register 
you want to fill the RastPort with. 

Scrolling a Sub-rectangle of a Raster 

You can scroll a sub-rectangle of a raster in any direction-up, down, left, right, or diagonally. To perform a scroll, 
you use the ScrollRaster() routine and specify a dx and dy (delta-x, delta-y) by which the rectangle image should 
be moved relative to the (0,0) location. 



As a result of this operation, the data within the rectangle will become physically smaller by the size of delta-x and 
delta-y, and the area vacated by the data when it has been cropped and moved is filled with the background color 
(color in BgPen). ScrollRasterQ is affected by the Mask setting. 

Here is the syntax of the ScrollRaster() function: 

ScrollRaster (&rastPort , dx, dy, xmin, ymin, xmax, ymax); 

The &rastPort argument is a pointer to a RastPort. The dx and dy arguments are the distances (positive, 0, or 
negative) to move the rectangle. The outer bounds of the sub-rectangle are defined by the xmin, xmax, ymin 
and ymax arguments. 

Here are some examples that scroll a sub-rectangle: 

/* scroll up 2 */ 

ScrollRaster (krastPort, 0, 2, 10, 10, 50, 50); 



/* scroll right 1 */ 
ScrollRaster f&rastPort , 



-1, 0, 10, 10, 50, 50) 



When scrolling a Simple Refresh window (or other layered RastPort), ScrollRasterQ scrolls the appropriate 
existing damage region. Refer to the "Intuition Windows" chapter for an explanation of Simple Refresh windows 
and damage regions. 

When scrolling a SuperBitMap window ScrollRasterQ requires a properly initialized TmpRas. The TmpRas 
must be initialized to the size of one bitplane with a width and height the same as the SuperBitMap, using the 
technique described in the "Area-Fill Information" section above. 

If you are using a SuperBitMap Layer, it is possible that the information in the BitMap is not fully reflected in the 
layer and vice-versa. Two graphics calls, CopySBitMapQ and SyncSBitMapQ, remedy these situations. Again, 
refer to the "Intuition Windows" chapter for more on this. 
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Drawing through a Stencil 



The routine BltPatternQ allows you to change only a very selective portion of a drawing area. Basically, this 
routine lets you define a rectangular region to be affected by a drawing operation and a mask of the same size 
that further defines which pixels within the rectangle will be affected. 

The figure below shows an example of what you can do with BltPatternQ. 
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Result of BitPatternO : 
Figure 27-17: Example of Drawing Through a Stencil 



In the resulting drawing, the lighter squares show where the target drawing area has been affected. Exactly what 
goes into the drawing area when the mask has 1's is determined by your RastPort's FgPen, BgPen, DrawMode 
and AreaPtrn fields. 

You call BltPattern() with: 

BltPattern (&rastport , mask, xl, yl, maxx, maxy, bytecnt) 

The &rastport argument specifies the RastPort to use. The operation will be confined to a rectangular area 
within the RastPort specified by xl and yl (upper right corner of the rectangle) and maxx and maxy (lower right 
corner of the rectangle). 

The mask is a pointer to the mask to use. This can be NULL, in which case a simple rectangular region is 
modified. Or it can be set to the address of a byte pattern which allows any arbitrary shape within the rectangle to 
be defined. The bytecount is the number of bytes per row for the mask (it must be an even number of bytes). 

The mask parameter is a rectangularly organized, contiguously stored pattern. This means that the pattern is 
stored in sequential memory locations stored as (maxy - yl + 1) rows of bytecnt bytes per row. These patterns 
must obey the same rules as BitMaps. This means that they must consist of an even number of bytes per row 
and must be stored in memory beginning at a legal word address. (The mask for BltPatternQ does not have to be 
in Chip RAM, though.) 
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Extracting from a Bit-packed Array 

You use the routine BltTemplate() to extract a rectangular area from a source area and place it into a destination 
area. The following figure shows an example. 

Array Start -->• •••••••••***•• •<-- Line 1 end 

Line 1 end +]_-->•••••••••••*•••• 



Character starts 10-bits 
in from starting point on 
the left edge of the array. 

Figure 27-18: Example of Extracting from a Bit-Packed Array 

For a rectangular bit array to be extracted from within a larger, rectangular bit array, the system must know how 
the larger array is organized. For this extraction to occur properly, you also need to tell the system the modulo for 
the inner rectangle. The modulo is the value that must be added to the address pointer so that it points to the 
correct word in the next line in this rectangularly organized array. 

The following figure represents a single bitplane and the smaller rectangle to be extracted. The modulo in this 
instance is 4, because at the end of each line, you must add 4 to the address pointer to make it point to the first 
word in the smaller rectangle. 



20 21 22 23 24 25 26 27 

28 29 30 31 32 33 34 35 

36 37 | 38 39 40 41 42 43 

< 

44 45 J 46 47 48 49 50 51 

52 53 J 54 55 56 57 58 59 

60 61 62 63 64 65 66 67 



<-- Larger source 
bit -plane image 



Smaller rectangle 
to be extracted 



Figure 27-19: Modulo 

Warning: The modulo value must be an even number of bytes. 
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BltTemplate() takes the following arguments: 

BltTemplate (source, srcX, srcMod, fcdestRastPort, destx, destY, sizeX, sizeY) ; 

The source argument specifies the rectangular bit array to use as the source template. Set this to the address of 
the nearest word (rounded down) that contains the first line of the source rectangle. The srcX argument gives the 
exact bit position (0-15) within the source address at which the rectangular bit array begins. The srcMod 
argument sets the source modulo so the next line of the rectangular bit array can be found. 

The data from the source rectangle is copied into the destination RastPort specified by destRastPort. The destX 
and destY arguments indicate where the data from the source rectangle should be positioned within the 
destination RastPort. The sizeX and sizeY arguments indicate the dimensions of the data to be moved. 

BltTemplateQ uses FgPen, BgPen, DrawMode and Mask to place the template into the destination area. This 
routine differs from BltPatternQ in that only a solid color is deposited in the destination drawing area, with or 
without a second solid color as the background (as in the case of text). Also, the template can be arbitrarily 
bit-aligned and sized in x. 

Copying Rectangular Areas 

Four routines use the blitter to copy rectangular areas from one section of a BitMap to another: BltBitMap(), 
BltBitMapRastPort(), BltMaskBitMapRastPort(), and ClipBlit(). All four of these blitter routines take a special 
argument called a minterm. 

The minterm variable is an unsigned byte value which represents an action to be performed during the move. 
Since all the blitter routines uses the hardware blitter to move the data, they can take advantage of the blitter's 
ability to logically combine or change the data as the move is made. The most common operation is a direct copy 
from source area to destination, which uses a minterm set to hex value CO. 

You can determine how to set the minterm variable by using the logic equations shown in the following tables. B 
represents data from the source rectangle and C represents data in the destination area. 

Table 27-7: Minterm Logic Equations 



Leftmost 4 Bits 
of MinTermin 

8 

4 
2 
1 



Logic Term Included 
Final Output 

BC "B AND C" 
BC "B AND NOT 
BC "NOT B AND 



BC 



'NOT B AND NOT C" 



You can combine values to select the logic terms. For instance a minterm value of OxCO selects the first two logic 
terms in the table above. These logic terms specify that in the final destination area you will have data that occurs 



in source B only. Thus, CO means a direct copy. The logic equation for this is: 

BC + BC = B(C + C) = B 
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Logic equations may be used to decide on a number of different ways of moving the data. For your convenience, 
a few of the most common ones are listed below. 

Table 27-8: Some Common MinTerm Values to Use for Copying 

MinTerm Value Logic Operation Performed During Copy 

3 Replace destination area with inverted source B. 

50 Replace destination area with an inverted version of itself. 

60 Put B where C is not, put C where B is not (cookie cut) . 

80 Only put bits into destination where there is a bit in the same 
position for both source and destination (sieve operation) . 

CO Plain vanilla copy from source B to destination C. 

The graphics library blitter routines all accept a minterm argument as described above. BltBitMap() is the basic 
blitter routine, moving data from one BitMap to another. 

BltBitMap() allows you to define a rectangle within a source BitMap and copy it to a destination area of the same 
size in another (or even the same) BitMap. This routine is used by the graphics library itself for rendering. 
BltBitMap() returns the number of planes actually involved in the blit. The syntax for the function is: 

ULONG planes; 

planes = BltBitMap (&srcBM, srcX, srcY, &dstBM, dstX, dstY, 
sizeX, sizeY, minterm, mask, tempA) ; 

The source bitmap is specified by the &srcBM argument. The position of the source area within the bitmap is 
specified by srcX and srcY. The destination bitmap is specified by the &dstBM argument. The position of the 
destination area within the bitmap is specified by dstX and dstY. 

The dimensions (in pixels) of the area to be moved is indicated by the sizeX and sizeY arguments. With the 
original custom chip set, the blitter size limits are 992 x 1024. With ECS the blitter size limits are 32,736 x 32,768. 
See the section on "Determining Chip Versions" earlier in this chapter to find out how to tell if the host system has 
ECS installed. 

The minterm argument determines what logical operation to perform on the rectangle data as bits are moved 
(described above). The mask argument, normally set to Oxff, specifies which bitplanes will be involved in the blit 
operation and which will be ignored. If a bit is set in the mask byte, the corresponding bitplane is included. The 
tempA argument applies only to blits that overlap and, if non-NULL, points to Chip memory the system will use for 
temporary storage during the blit. 
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BltBitMapRastPortQ takes most of the same arguments as BltBitMap(), but its destination is a RastPort instead 
of a BitMap. The syntax for the function is: 

VOID BltBitMapRastPort (&srcBM, srcX, srcY, &dstRP, dstX, dstY, 
sizeX, sizeY, minterm) ; 

The arguments here are the same as for BltBitMap() above. Note that the BltBitMapRastPortQ function will 
respect the RastPort.Mask field. Only the planes specified in the Mask will be included in the operation. 

A third type of blitter operation is provided by the BltMaskBitMapRastPortQ function. This works the same as 
BltBitMapRastPortQ except that it takes one extra argument, a pointer to a single bitplane mask of the same 
height and width as the source. The mask acts as a filter for the operation-a blit only occurs where the mask 



plane is non-zero. The syntax for the function is: 

VOID BltMaskBitMapRastPort (&srcBM, srcX, srcY, &dstRP, dstx, dstY, 
sizeX, sizeY, minterm, bltmask) ; 

The bltmask argument points to a word-aligned mask bitplane in Chip memory with the same dimensions as the 
source bitmap. Note that this function ignores the Mask field of the destination RastPort. 

ClipBlitQ takes most of the same arguments as the other blitter calls described above but it works with source 
and destination RastPorts and their layers. Before ClipBlit() moves data, it looks at the area from which and to 
which the data is being copied (RastPorts, not BitMaps) and determines if there are overlapping areas involved. 
If so, it splits up the overall operation into a number of bitmaps to move the data in the way you request. To call 
ClipBlit() use: 

VOID ClipBlit (&srcRP, srcX, srcY, &dstRP, dstx, dstY, XSize, YSize, minterm) ; 

Since ClipBlitQ respects the Layer of the source and destination RastPort, it is the easiest blitter movement call 
to use with Intuition windows. The following code fragments show how to save and restore an undo buffer using 
ClipBlit(). 

/* Save work rastport to an undo rastport */ 

ClipBlit (kdrawRP, 0, 0, &undoRP, 0, 0, areaWidth, areaHeight, OxCO); 

/* restore undo rastport to work rastport */ 

ClipBlit (kundoRP, 0, 0, &drawRP, 0, 0, areaWidth, areaHeight, OxCO); 

Scaling Rectangle Area 

BitMapScale() will scale a single bitmap any integral size up to 16,383 times its original size. This function is 
available only in Release 2 and later versions of the OS. It is called with the address of a BitScaleArgs structure 
(see <graphics/scale.h>). 

void BitMapScale (struct BitScaleArgs *bsa) 

The bsa argument specifies the BitMaps to use, the source and destination rectangles, as well as the scaling 
factor. The source and destination may not overlap. The caller must ensure that the destination BitMap is large 
enough to receive the scaled-up copy of the source rectangle. The function ScalerDiv() is provided to help in the 
calculation of the destination BitMap's size. 
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When to Wait for the Blitter 

This section explains why you might have to call WaitBlit(), a special graphics function that suspends your task 
until the blitter is idle. Many of the calls in the graphics library use the Amiga's hardware blitter to perform their 
operation, most notably those which render text and images, fill or pattern, draw lines or dots and move blocks of 
graphic memory. 

Internally, these graphics library functions operate in a loop, doing graphic operations with the blitter one plane at 
a time as follows: 

OwnBlitter ( ) ; /* Gain exclusive access to the hardware blitter */ 

f or (planes=0 ; planes < bitmap- >depth; planes++) 

{ 

WaitBlitO; /* Sleep until the previous blitter operation */ 
/* completes start a blit */ 

} 

DisownBlitter ( ) ; /* Release exclusive access to the hardware blitter */ 

Graphics library functions that are implemented this way always wait for the blitter at the start and exit right after 
the final blit is started. It is important to note that when these blitter-using functions return to your task, the final (or 
perhaps only) blit has just been started, but not necessarily completed. This is efficient if you are making many 



such calls in a row because the next graphics blitter call always waits for the previous blitter operation to complete 
before starting its first blit. 

However, if you are intermixing such graphics blitter calls with other code that accesses the same graphics 
memory then you must first WaitBlit() to make sure that the final blit of a previous graphics call is complete before 
you use any of the memory. For instance, if you plan to immediately deallocate or reuse any of the memory areas 
which were passed to your most recent blitter-using function call as a source, destination, or mask, it is imperative 
that you first call WaitBlit(). 

Warning: If you do not follow the above procedure, you could end up with a program that 
works correctly most of the time but crashes sometimes. Or you may run into problems when 
your program is run on faster machines or under other circumstances where the blitter is not 
as fast as the processor. 

Accessing the Blitter Directly 

To use the blitter directly, you must first be familiar with how its registers control its operation. This topic is 
covered thoroughly in the Amiga Hardware Reference Manual and is not repeated here. There are two basic 
approaches you can take to perform direct programming of the blitter: synchronous and asynchronous. 

Synchronous programming of the blitter is used when you want to do a job with the blitter right away. 
For synchronous programming, you first get exclusive access to the blitter with OwnBlitter(). Next call 
WaitBlit() to ensure that any previous blitter operation that might have been in progress is completed. 
Then set up your blitter operation by programming the blitter registers. Finally, start the blit and call 
DisownBlitterQ. 

Asynchronous programming of the blitter is used when the blitter operation you want to perform does not 
have to happen immediately. In that case, you can use the QBIitQ and QBSBIit() functions in order to 
queue up requests for the use of the blitter on a non-exclusive basis. You share the blitter with system 
tasks. 
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Whichever approach you take, there is one rule you should generally keep in mind about using the blitter directly: 

Don't Tie Up The Blitter. The system uses the blitter extensively for disk and display operation. 
While your task is using the blitter, many other system processes will be locked out. 
Therefore, use it only for brief periods and relinquish it as quickly as possible. 

To use QBIit() and QBSBIit(), you must create a data structure called a bltnode (blitter node) that contains a 
pointer to the blitter code you want to execute. The system uses this structure to link blitter usage requests into a 
first-in, first-out (FIFO) queue. When your turn comes, your own blitter routine can be repeatedly called until your 
routine says it is finished using the blitter. 

Two separate blitter queues are maintained. One queue is for the QBIitQ routine. You use QBIitQ when you 
simply want something done and you do not necessarily care when it happens. This may be the case when you 
are moving data in a memory area that is not currently being displayed. 

The second queue is maintained for QBSBIit(). QBS stands for "queue-beam-synchronized". QBSBIit() requests 
form a beam-synchronized FIFO queue. When the video beam gets to a predetermined position, your blitter 
routine is called. Beam synchronization takes precedence over the simple FIFO. This means that if the beam 
sync matches, the beam-synchronous blit will be done before the non-synchronous blit in the first position in the 
queue. You might use QBSBIit() to draw into an area of memory that is currently being displayed to modify 
memory that has already been "passed-over" by the video beam. This avoids display flicker as an area is being 
updated. 

The sole input to both QBIitQ and QBSBIitQ is a pointer to a bltnode data structure, defined in the include file 
<hardware/blit.h>. Here is a copy of the structure, followed by details about the items you must initialize: 

struct bltnode 

{ 

struct bltnode *n; 

int (*function) () ; 

char stat; 



}; 



short blitsize; 
short beamsync; 
int (*cleanup) 



struct bltnode *n; 

This is a pointer to the next bltnode, which, for most applications will be zero. You should not link 
bltnodes together. This is to be performed by the system in a separate call to QBIit() or QBSBIit(). 

int (*function)( ); 

This is the address of your blitter function that the blitter queuer will call when your turn comes up. 
Your function must be formed as a subroutine, with an RTS instruction at the end. Follow Amiga 
programming conventions by placing the return value in DO (or in C, use return(value)). 

If you return a nonzero value, the system will call your routine again next time the blitter is idle until you 
finally return 0. This is done so that you can maintain control over the blitter; for example, it allows you 
to handle all five bitplanes if you are blitting an object with 32 colors. For display purposes, if you are 
blitting multiple objects and then saving and restoring the background, you must be sure that all planes 
of the object are positioned before another object is overlaid. This is the reason for the lockup in the 
blitter queue; it allows all work per object to be completed before going on to the next one. 
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Note: Not all C compilers can handle *function() properly! The system actually tests the processor 
status codes for a condition of equal-to-zero (Z flag set) or not-equal-to-zero (Z flag clear) when your 
blitter routine returns. Some C compilers do not set the processor status code properly (i.e., according 
to the value returned), thus it is not possible to use such compilers to write the (*function)()) routine. In 
that case assembly language should be used. Blitter functions are normally written in assembly 
language anyway so they can take advantage of the ability of QBIitQ and QBSBIit() to pass them 
parameters in processor registers. 

The register passing conventions for these routines are as follows. Register A0 receives a pointer to 
the system hardware registers so that all hardware registers can be referenced as an offset from that 
address. Register A1 contains a pointer to the current bltnode. You may have queued up multiple 
blits, each of which perhaps uses the same blitter routine. You can access the data for this particular 
operation as an offset from the value in A1 . For instance, a typical user of these routines can 
precalculate the blitter register values to be placed in the blitter registers and, when the routine is 
called, simply copy them in. For example, you can create a new structure such as the following: 

INCLUDE "exec/types. i" 
INCLUDE "hardware/blit . i" 

STRUCTURE mybltnode,0 

; Make this new structure compatible with a 
; bltnode by making the first element a bltnode structure. 
STRUCT bltnode, bn_SIZEOF 

; Blitter control register 1. 
; First and last word masks . 

; Modulos for sources a, b,and c. 

; add anything else you want 
LABEL mbn_SIZEOF 

Other forms of data structures are certainly possible, but this should give you the general idea. 

char stat; 

Tells the system whether or not to execute the clean-up routine at the end. This byte should be set to 
CLEANUP (0x40) if cleanup is to be performed. If not, then the bltnode cleanup variable can be zero. 

short beamsync; 

The value that should be in the VBEAM counter for use during a beam-synchronous blit before the 
functionQ is called. The system cooperates with you in planning when to start a blit in the routine 



bltconl 




fwmask 




lwmask 




bltmda 




bltmdb 




bltmdc 




any more 


_data 



QBSBIitO by not calling your routine until, for example, the video beam has already passed by the area 
on the screen into which you are writing. This is especially useful during single buffering of your 
displays. There may be time enough to write the object between scans of the video display. You will 
not be visibly writing while the beam is trying to scan the object. This avoids flicker (part of an old 
view of an object along with part of a new view of the object). 

int (*cleanup)(); 

The address of a routine that is to be called after your last return from the QBIitQ routine. When you 
finally return a zero, the queuer will call this subroutine (ends in RTS or return()) as the clean-up. 
Your first entry to the function may have dynamically allocated some memory or may have done 
something that must be undone to make for a clean exit. This routine must be specified. 
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User Copper Lists 

The Copper coprocessor allows you to produce mid-screen changes in certain hardware registers in addition to 
changes that the system software already provides. For example, it is the Copper that allows the Amiga to split 
the viewing area into multiple draggable screens, each with its own independent set of colors. 

To create your own mid-screen effects on the system hardware registers, you provide "user Copper lists" that can 
be merged into the system Copper lists. 

In the ViewPort data structure there is a pointer named UCoplns. If this pointer value is non-NULL, it points to a 
user Copper list that you have dynamically allocated and initialized to contain your own special hardware-stuffing 
instructions. 

You allocate a user Copper list by an instruction sequence such as the following: 

Struct UCopList *uCopList = NULL; 

/* Allocate memory for the Copper list. Make certain that the */ 
/* initial memory is cleared. */ 

uCopList = (struct UCopList *) 

AllocMem(sizeof (struct UCopList), MEMF_PUBLIC | MEMF_CLEAR) ; 

if (uCopList == NULL) 
return (FALSE) ; 

Note: User Copper lists do not have to be in Chip RAM. 

Copper List Macros 

Once this pointer to a user Copper list is available, you can use it with system macros (<graphics/gfxmacros.h>) 
to instruct the system what to add to its own list of things for the Copper to do within a specific ViewPort. The file 
<graphics/gfxmacros.h> provides the following five macro functions that implement user Copper instructions. 

CINIT initializes the Copper list buffer. It is used to specify how many instructions are going to be placed in the 
Copper list. It is called as follows. 

CINIT (uCopList , num_entries) ; 

The uCopList argument is a pointer tot he user Copper list and num_entries is the number of entries in the list. 

CWAIT waits for the video beam to reach a particular horizontal and vertical position. Its format is: 

CWAIT (uCopList, v, h) 

Again, uCopList is the pointer to the Copper list. The v argument is the vertical position for which to wait, 
specified relative to the top of the ViewPort. The legal range of values (for both NTSC and PAL) is from to 255; 
h is the horizontal position for which to wait. The legal range of values (for both NTSC and PAL) is from to 226. 
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CMOVE installs a particular value into a specified system register. Its format is: 

CMOVE (uCopList, reg, value) 

Again, uCopList is the pointer to the Copper list. The reg argument is the register to be affected, specified in this 
form: custom. register-name where the register-name is one of the registers listed in the Custom structure in 
<hardware/custom.h>. The value argument to CMOVE is the value to place in the register. 

CBump increments the user Copper list pointer to the next position in thelist. It is usually invoked for the 
programmer as part of the macro definitions CWAIT or CMOVE. Its format is: 

CBump (uCopList) 

where uCopList is the pointer to the user Copper list. 
CEND terminates the user Copper list. Its format is: 

CEND (uCopList) 

where uCopList is the pointer to the user Copper list. 

Executing any of the user Copper list macros causes the system to dynamically allocate special data structures 
called intermediate Copper lists that are linked into your user Copper list (the list to which uCopList points) 
describing the operation. When you call the function MrgCop(&view) as shown in the section called "Forming A 
Basic Display," the system uses all of its intermediate Copper lists to sort and merge together the real Copper lists 
for the system (LOFCprList and SHFCprList). 

When your program exits, you must return to the system all of the memory that you allocated or caused to be 
allocated. This means that you must return the intermediate Copper lists, as well as the user Copper list data 
structure. Here are two different methods for returning this memory to the system. 

/* Returning memory to the system if you have NOT 

* obtained the Viewport from Intuition. */ 
FreeVPortCopLists (viewport) ; 

/* Returning memory to the system if you HAVE 

* obtained the Viewport from Intuition. */ 
CloseScreen (screen) ; /* Intuition only */ 

User Copper lists may be clipped, under Release 2 and later, to ViewPort boundaries if the appropriate tag 
(VTAGJJSERCLIPSET) is passed to VideoControl(). Under earlier releases, the user Copper list would "leak" 
through to lower Viewports. 

Copper List Example 

The example program below shows the use of user Copper lists under Intuition. 

/* The example program below shows the use of user Copper lists 
under Intuition. 

UserCopperExample . c 
User Copper List Example 
For SAS/C 5.10a, 

compile with: LC -bl -cfist -L -v -y UserCopperExample . c 
link with lc.lib and amiga.lib 
*/ 

#include <exec/types .h> 
#include <exec/memory . h> 
#include <graphics/gfxbase . h> 
#include <graphics/gfxmacros . h> 
#include <graphics/copper . h> 
#include <graphics/videocontrol . h> 
#include <intuition/intuition.h> 
#include <intuition/pref erences .h> 
#include <hardware/custom.h> 



#include <libraries/dos .h> 

#include <clib/exec_protos . h> /* Prototypes. */ 

#include <clib/graphics_protos . h> 
#include <clib/intuition_protos . h> 
#include <clib/dos_protos . h> 

#include <stdlib.h> 

/* Use this structure to gain access to the custom registers. */ 
extern struct Custom far custom; 

/* Global variables. */ 

struct Gf xBase *Gf xBase = NULL; 

struct IntuitionBase *IntuitionBase = NULL; 

struct Screen *screen = NULL; 

struct Window *window = NULL; 

VOID main( VOID ), cleanExit ( WORD ); 
WORD openAll ( VOID ), loadCopper ( VOID ); 

/* 
* The main ( ) routine -- just calls subroutines 

*/ 

VOID main ( VOID ) 

{ 

WORD ret_val ; 

struct IntuiMessage *intuiMessage; 

/* Open the libraries, a screen and a window. */ 

ret_val = openAll () ; 

if (RETURNJOK == ret_val) 

{ 

/* Create and attach the user Copper list. */ 
ret_val = loadCopper ( ) ; 
if (RETURNJOK == ret_val) 

{ 

/* Wait until the user clicks in the close gadget. */ 
(VOID) Wait (l<<window->UserPort->mp_SigBit) ; 

while (intuiMessage = (struct IntuiMessage *) GetMsg (window->UserPort) ) 
ReplyMsg ( (struct Message *) intuiMessage) ; 



} 



} 

cleanExit (ret val) ; 



/* 

* openAll () -- opens the libraries, screen and window 

*/ 

WORD openAll ( VOID ) 

{ 

#define MY_WA_WIDTH 270 /* Width of window. */ 

WORD ret_val = RETURNJOK; 

/* Prepare to explicitly request Topaz 60 as the screen font. *, 
struct TextAttr topaz60 = 

{ 

(STRPTR) "topaz. font" , 

( UWORD ) TOPAZ_S IXTY , ( UBYTE ) , ( UBYTE ) 

}; 

GfxBase = (struct GfxBase *) OpenLibrary ( "graphics . library" , 37L) ; 
if (GfxBase == NULL) 

ret_val = ERROR_INVALID_RESIDENT_LIBRARY; 
else 

{ 

IntuitionBase = (struct IntuitionBase *) 

OpenLibrary ( "intuition. library" , 37L) ; 

if (IntuitionBase == NULL) 



ret val 



else 



ERROR INVALID RESIDENT LIBRARY; 



screen = OpenScreenTags ( NULL, 



SA_Overscan, 
SA_Title, 
SA_Font , 
TAG DONE) ; 



OSCAN_STANDARD , 

"User Copper List Example" 

(ULONG) &topaz60, 



if (NULL == screen) 

ret_val = ERROR_NO_FREE_STORE ; 
else 



{ 



window 



OpenWindowTags ( NULL , 
WA CustomScreen, screen, 



WA_Title, "<- Click here to quit.", 

WA_IDCMP, CLOSEWINDOW, 

WA_Flags , WINDOWDRAG | WINDOWCLOSE | INACTIVEWINDOW, 

WA_Left, ( screen- >Width-MY_WA_WIDTH) /2 , 

WA_Top, screen->Height/2 , 

WA_Height, screen->Font->ta_YSize + 3, 

WA_Width, MY_WA_WIDTH, 
TAG_DONE) ; 

if (NULL == window) 

ret val = ERROR NO FREE STORE; 



return (ret val) 



/* 

* loadCopperO -- creates a Copper list program and adds it to the system 

*/ 

WORD loadCopper ( VOID ) 

{ 

register USHORT i, scanlines_per_color ; 
WORD ret_val = RETURNJDK; 
struct Viewport *viewPort; 
struct UCopList *uCopList = NULL; 
struct Tagltem uCopTags [] = 



{ 



}; 



{ VTAG_USERCLIP_SET, NULL }, 
{ VTAG_END_CM, NULL } 



spectrum [] 
{ 



0x0604, 
0x0629, 
0x077e, 
0x03f3, 
0x0e60, 



0x0605, 
0x072a, 
0x088f , 



0x0606, 0x0607, 0x0617, 0x0616 



0x073b, 
0x07af , 



0x074b, 
0x06cf , 



0x074c, 
0x05ff , 



0x075d, 
0x04fb, 



0x076e, 
0x04f 7, 



0x07f2, OxObfl, OxOffO, OxOfcO, OxOeaO , 0x0e80, 
0x0d40, 0x0d20, OxOdOO 



}; 



#define NUMCOLORS 3 2 



/* Allocate memory for the Copper list. */ 

/* Make certain that the initial memory is cleared. */ 

UCopList = (struct UCopList *) 

AllocMem(sizeof (struct UCopList), MEMF_PUBLIC | MEMF_CLEAR) ; 

if (NULL == UCopList) 

ret_val = ERROR_NO_FREE_STORE ; 
else 

{ 

/* Initialize the Copper list buffer. */ 
CINIT(uCopList, NUMCOLORS); 



scanlinespercolor = screen->Height/NUMCOLORS; 



/* Load in each color. */ 
for (i=0; i<NUMCOLORS; i++) 

{ 

CWAIT (uCopList , ( i*scanlines_per_color) , 0) ; 

CMOVE (uCopList , custom. color [0] , spectrum [i] ) ; 

} 

CEND (uCopList) ; /* End the Copper list */ 

viewport = ViewPortAddress (window) ; /* Get a pointer to the Viewport. */ 
Forbid () ; /* Forbid task switching while changing the Copper list. */ 
viewport ->UCopIns=uCopList ; 
Permit (); /* Permit task switching again. */ 

/* Enable user copper list clipping for this Viewport. */ 
(VOID) VideoControl ( viewport ->ColorMap, uCopTags ) ; 

RethinkDisplay ( ) ; /* Display the new Copper list. */ 

return (ret_val) ; 
} 
} 

/* 
* cleanExitO -- returns all resources that were used. 

*/ 

VOID cleanExit ( WORD retval ) 

{ 

struct Viewport *viewPort; 

if (NULL != IntuitionBase) 

{ 

if (NULL != screen) 

{ 

if (NULL != window) 

{ 

viewport = ViewPortAddress (window) ; 
if (NULL != viewport ->UCopIns) 

{ 

/* Free the memory allocated for the Copper. */ 
FreeVPortCopLists (viewport) ; 
RemakeDisplay ( ) ; 

} 

CloseWindow (window) ; 

} 

CloseScreen (screen) ; 

} 

CloseLibrary ( (struct Library *) IntuitionBase) ; 

} 

if (NULL != Gf xBase) 

CloseLibrary ( (struct Library *)GfxBase); 

exit ( (int) retval) ; 
} 
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ECS and Genlocking Features 

The Enhanced Chip Set (ECS) Denise chip (8373-R2a), coupled with the Release 2 graphics library, opens up a 
whole new set of genlocking possibilities. Unlike the old Denise, whose only genlocking ability allowed keying on 
color register zero, the ECS Denise allows keying on any color register. Also, the ECS Denise allows keying on 
any bitplane of the ViewPort being genlocked. With the ECS Denise, the border area surrounding the display can 
be made transparent (always passes video) or opaque (overlays using color 0). All the new features are set 
individually for each ViewPort. These features can be used in conjunction with each other, making interesting 
scenarios possible. 



Genlock Control 

Using VideoControl(), a program can enable, disable, or obtain the state of a Viewport's genlocking features. It 
returns NULL if no error occurred. The function uses a tag based interface: 

error = BOOL VideoControl ( struct ColorMap *cm, struct Tagltem *ti ) ; 

The ti argument is a list of video commands stored in an array of Tagltem structures. The cm argument specifies 
which ColorMap and, indirectly, which ViewPort these genlock commands will be applied to. The possible 
commands are: 

VTAG_BITPLANEKEY_GET, _SET, _CLR 
VTAG_CHROMA_PLANE_GET , _SET 
VTAG_BORDERBLANK_GET , _SET, _CLR 
VTAG_BORDERNOTRANS_GET , _SET, _CLR 
VTAG_CHROMAKEY_GET , _SET, _CLR 
VTAG_CHROMAPEN_GET , _SET, _CLR 

This section covers only the genlock VideoControlQ tags. See <graphics/videocontrol.h> for a complete list of all 
the available tags you can use with VideoControl(). 

VTAG_BITPLANEKEY_GET is used to find out the status of the bitplane keying mode. 
VTAG_BITPLANEKEY_SET and VTAG_BITPLANEKEY_CLR activate and deactivate bitplane keying mode. If 
bitplane key mode is on, genlocking will key on the bits set in a specific bitplane from the ViewPort (the specific 
bitplane is set with a different tag). The data portion of these tags is NULL. 

For inquiry commands like VTAGJ3ITPLANEKEYGET (tags ending in _GET), VideoControlQ changes the 

_GET tag ID (ti_Tag) to the corresponding _SET or _CLR tag ID, reflecting the current state of the genlock mode. 

For 

example, when passed the following tag array: 

struct Tagltem videocommands [] = 

{ 

{VTAG_BITPLANEKEY_GET, NULL}, 
{VTAG_END_CM, NULL} 

}; 

VideoControl() changes the VTAG_BITPLANEKEY_GET tag ID (ti_Tag) to VTAG_BITPLANEKEY_SET if 
bitplane keying is currently on, or to VTAG_BITPLANEKEY_CLR if bitplane keying is off. In both of these cases, 
VideoControl() only uses the tag's ID, ignoring the tag's data field (ti_Data). 

The VTAG_CHROMA_PLANE_GET tag returns the number of the bitplane keyed on when bitplane keying mode 
is on. VideoControlQ changes the tag's data value to the bitplane number. VTAG_CHROMA_PLANE_SET sets 
the bitplane number to the tag's data value. 
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VTAG_BORDERBLANK_GET is used to obtain the border blank mode status. This tag works exactly like 
VTAG_BITPLANEKEY_GET. VideoControl() changes the tag's ID to reflect the current border blanking state. 
VTAG_BORDERBLANK_SET and VTAG_BORDERBLANK_CLR activate and deactivate border blanking. If 
border blanking is on, the Amiga will not display anything in its display border, allowing an external video signal to 
show through the border area. On the Amiga display, the border appears black. The data portion of these tags is 
NULL. 

The VTAG_BORDERNOTRANS_GET, _SET and _CLR tags are used, respectively, to obtain the status of 
border-not-transparent mode, and to activate and to deactivate this mode. If set, the Amiga display's border will 
overlay external video with the color in register 0. Because border blanking mode takes precedence over 
border-not-transparent mode, setting border-not-transparent has no effect if border blanking is on. The data 
portion of these tags is NULL. 

The VTAG_CHROMAKEY_GET, _SET and _CLR tags are used, respectively, to obtain the status of chroma 
keying mode, and to activate and deactivate chroma keying mode. If set, the genlock will key on colors from 
specific color registers (the specific color registers are set using a different tag). If chroma keying is not set, the 
genlock will key on color register 0. The data portion of these tags is NULL. 



VTAG_CHROMAPEN_GET obtains the chroma keying status of an individual color register. The tag's ti_Data 
field contains the register number. Like the other _GET tags, VideoControl() changes the tag ID (ti_Tag) to one 
that reflects the current state of the mode. VTAG_CHROMAPEN_SET and VTAG_CHROMAPEN_CLR activate 
and deactivate chroma keying for each individual color register. Chroma keying can be active for more than one 
register. By turning off border blanking and activating chroma keying mode, but turning off chroma keying for 
each color register, a program can overlay every part of an external video source, completely blocking it out. 

After using VideoControl() to set values in the ColorMap, the corresponding ViewPort has to be rebuilt with 
MakeVPortQ, MrgCopQ and LoadView(), so the changes can take effect. A program that uses a screen's 
ViewPort rather than its own ViewPort should use the Intuition functions MakeScreen() and RethinkDisplayQ to 
make the display changes take effect. 

The following code fragment shows how to access the genlock modes. 

struct Screen *genscreen; 
struct ViewPort *vp; 
struct Tagltem vtags [24] ; 

/* The complete example opened a window, rendered some colorbars, */ 
/* and added gadgets to allow the user to turn the various genlock */ 
/* modes on and off. */ 

vp = & (genscreen->ViewPort) ; 

/* Ascertain the current state of the various modes. */ 

/* Is borderblanking on? */ 

vtags [0] .ti_Tag = VTAG_BORDERBLANK_GET ; 

vtags [0] . ti_Data = NULL; 

/* Is bordertransparent set? */ 

vtags [1] .ti_Tag = VTAG_BORDERNOTRANS_GET ; 

vtags [1] . ti_Data = NULL; 

/* Key on bitplane? */ 

vtags [2] .ti_Tag = VTAG_BITPLANEKEY_GET; 

vtags [2] .ti_Tag = NULL; 

/* Get plane which is used to key on */ 
vtags [3] .ti_Tag = VTAG_CHROMA_PLANE_GET ; 
vtags [3] . ti_Data = NULL; 

/* Chromakey overlay on? */ 

vtags [4] .ti_Tag = VTAG_CHROMAKEY_GET ; 

vtags [4] . ti_Data = NULL; 

for (i = 0; i < 16; i++) 

{ 

/* Find out which colors overlay */ 

vtags [i + 5].ti_Tag = VTAG_CHROMA_PEN_GET ; 

vtags [i + 5] . ti_Data = i; 
} 

/* Indicate end of tag array */ 
vtags [21] ,ti_Tag = VTAG_END_CM; 
vtags [21] . ti_Data = NULL; 

/* And send the commands. On return the Tags themselves will 
* indicate the genlock settings for this Viewport's ColorMap. 

*/ 

error = VideoControl (vp->ColorMap, vtags); 

/* The complete program sets gadgets to reflect current states. */ 

/* Will only send single commands from here on. */ 
vtags [1] . ti_Tag = VTAG_END_CM; 

/* At this point the complete program gets an input event and 

sets/clears the genlock modes as requested using the vtag list and 
VideoControl () . 



*/ 

/* send video command */ 

error = VideoControl (vp->ColorMap, vtags) ; 

/* Now use MakeScreen ( ) and RethinkDisplay ( ) to make the VideoControl ( ) 

* changes take effect. If we were using our own Viewport rather than 

* borrowing one from a screen, we would instead do: 

* MakeVPort (ViewAddress () , vp) ; 

* MrgCop (ViewAddress ( ) ) ; 

* LoadView (ViewAddres ( ) ) ; 

*/ 

MakeScreen (genscreen) ; 
RethinkDisplay ( ) ; 

/* The complete program closes and frees everything it had opened or 

allocated. 
*/ 

/* The complete example calls the CheckPAL function, which is included 

below in its entirety for illustrative purposes. 
*/ 

BOOL CheckPAL (STRPTR screenname) 

{ 

struct Screen *screen; 
ULONG modelD = LORES_KEY; 
struct Displaylnfo displayinfo; 
BOOL Is PAL; 

if (GfxBase->LibNode.lib_Version >= 36) 
{ 

/* 

* We got at least V36, so lets use the new calls to find out what 

* kind of videomode the user (hopefully) prefers. 
*/ 

if (screen = LockPubScreen (screenname) ) 
{ 

/* 

* Use graphics . library/GetVPModelD ( ) to get the ModelD of the 

* specified screen. Will use the default public screen 

* (Workbench most of the time) if NULL It is _very_ unlikely 

* that this would be invalid, heck it's impossible. 

*/ 

if ( (mode ID = GetVPModelD (& ( screen- >ViewPort) ) ) != INVALID_ID) 

{ 

/* 

* If the screen is in VGA mode, we can't tell whether the 

* system is PAL or NTSC. So to be foolproof we fall back 

* to the displayinfo of the default monitor by inquiring 

* about just the LORES_KEY displaymode if we don't know. 

* The default .monitor reflects the initial video setup of 

* the system, thus for either ntsc. monitor or pal. monitor. 

* We only use the displaymode of the is an alias specified 

* public screen if it's display mode is PAL or NTSC and 

* NOT the default. 

*/ 

if ( ! ( (modelD & MONITOR_ID_MASK) == NTSC_MONITOR_ID | | 
(modelD & MONITOR_ID_MASK) == PAL_MONITOR_ID) ) 
modelD = LORES_KEY; 

} 

UnlockPubScreen (NULL, screen); 
} /* if fails modelD = LORES_KEY. Can't lock screen, so fall back 
* on default monitor. 
*/ 

if (GetDisplayInfoData(NULL, (UBYTE *) & displayinfo, 
sizeof (struct Displaylnfo), DTAG_DISP, mode ID ) ) 

{ 

if (displayinfo. PropertyFlags & DIPF_IS_PAL) 



Is PAL = TRUE; 
else 

IsPAL = FALSE; 
/* Currently the default monitor is always either PAL or 
* NTSC. 
*/ 



else 

/* < V36. The enhancements to the videosystem in V36 (and above) 

* cannot be better expressed than with the simple way to determine 

* PAL in V34 . 
*/ 

IsPAL= (GfxBase->DisplayFlags & PAL) ? TRUE : FALSE; 

return (IsPAL) ; 



Function Reference 



The following are brief descriptions of the Amiga's graphics primitives. See the Amiga ROM Kernel Reference 
Manual: Includes and Autodocs for details on each function call. 

Table 27-9: Graphics Primitives Functions 



D i sp l ay S e t - up Funct i ons 
l n i tV ie w() 



— Descr i pt i on 

I n i t i a li zes tho V ie w structuro. 



InitBitMapO 

RASSIZE() 

AllocRaster() 

FreeRaster() 

lnitVPort() 

GetColorMap() 

FreeColorMapO 

LoadRGB4() 

SetRGB4CM() 

MakeVPort() 

MrgCop() 

LoadView() 

FreeCprList() 

FreeVPortCopLists() 

OFF_DISPLAY() 

ON_DISPLAY() 



Initializes the BitMap structure. 

Calculates the size of a Viewport's BitMap. 

Allocates the bitplanes needed for a BitMap. 

Frees the bitplanes created with AllocRaster(). 

Initializes the ViewPort structure. 

Returns the ColorMap structure used by Viewports. 

Frees the ColorMap created by GetColorMap(). 

Loads the color registers for a given ViewPort. 

Loads an individual color register for a given ViewPort. 

Creates the intermediate Copper list program for a ViewPort. 

Merges the intermediate Copper lists. 

Displays a given View. 

Frees the Copper list created with MrgCopO 

Frees the intermediate Copper lists created with MakeVPort(). 

Turns the video display DMA off 

Turns the video display DMA back on again. 
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Re l eas e 2 D i sp l ay 
Set-up Functions 
F i ndD i splay l nfoQ 



Description 

R e turns th e d i sp l ay databas e hand le for a g i v e n Mod el D (V36). 



GetDisplaylnfoData() 

VideoControl() 

GfxNew() 

GfxAssociate() 

GfxFree() 

OpenMonitor() 

CloseMonitor() 

GetVPModelD() 

ModeNotAvailableQ 



Looks up a display attribute in the display database (V36) 
Sets, clears and gets the attributes of an existing display (V36). 
Creates ViewExtra or ViewPortExtra used in Release 2 displays (V36). 
Attaches a ViewExtra to a View (V36). 

Frees the ViewExtra or ViewPortExtra created by GfxNew() (V36). 
Returns the MonitorSpec structure used in Release 2 Views (V36). 
Frees the MonitorSpec structure created by OpenMonitorQ (V36). 
Returns the Release 2 ModelD of an existing ViewPort (V36). 
Determines if a display mode is available from a given ModelD (V36). 



Drawing Functions 
l n i tRastPort() 



Description 

I n i t i a li ze a RastPort structure. 



lnitArea() 

SetWrMask() 

SetAPen() 

SetBPen() 

SetOPen() 

SetDrMode() 

SetDrPt() 

SetAfPt() 

Wr i toPixo l Q 



Initialize the Arealnfo structure used with a RastPort. 

Set the RastPort.Mask. 

Set the RastPort.FgPen foreground pen color. 

Set the RastPort. Bg Pen background pen color. 

Set the RastPort.AOIPen area fill outline pen color. 

Set the RastPort.DrawMode drawing mode. 

Set the RastPort.LinePtrn line drawing pattern. 

Set the RastPort area fill pattern and size. 

Draw a o i ng l o p i xo l i n tho foroground co l or at a g i von coord i nato. 



ReadPixel() 

DrawCircle() 

DrawEllipse() 

Move() 

Draw() 

PolyDrawQ — 



Find the color of the pixel at a given coordinate. 

Draw a circle with a given radius and center point. 

Draw an ellipse with the given radii and center point. 

Move the RastPort drawing pen to a given coordinate. 

Draw a line from the current pen location to a given coordinate. 

Draw a po l ygon w i th a g i ven set of vertices. 



AreaMove() 

AreaDraw() 

AreaEnd() 

BNDRYOFF() 

AreaCircle() 

AreaEllipseO 

Flood() 

RectFillQ 



Set the anchor point for a filled polygon. 

Add a new vertice to an area-fill polygon. 

Close and area-fill polygon, draw it and fill it. 

Turn off area-outline pen usage activated with SetOPen(). 

Draw a filled circle with a given radius and center point. 

Draw a filled ellipse with the given radii and center point. 

Flood fill a region starting at a given coordinate. 

Flood fill a rectangular area at a given location and size. 
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Data Movement Funct i ons 



D e scr i pt i on 



B l tC le ar() 



Us e th e hardwar e b li tt e r to c le ar a b l ock of m e mory. 



SetRast() 

ScrollRaster() 

BltPattern() 

BltTemplate() 

BltBitMap() 

BltBitMapRastPort() 



Fill the RastPort.BitMap with a given color. 

Move a portion of a RastPort.BitMap. 

Draw a rectangular pattern of pixels into a RastPort.BitMap. The 

x-dimension of the rectangle must be word-aligned and word-sized. 

Draw a rectangular pattern of pixels into a RastPort.BitMap. The 

x-dimension of the rectangle can be arbitrarily bit-aligned and sized. 

Copy a rectangular area from one BitMap to a given coordinate in another 

BitMap. 

Copy a rectangular area from a BitMap to a given coordinate in a 

RastPort.BitMap. 
BltMaskBitMapRastPort() Copy a rectangular area from a BitMap to a RastPort.BitMap through a 

mask bitplane. 
ClipBlitQ Copy a rectangular area from one RastPort to another with respect to their 

Layers. 
BitMapScaleQ Scale a rectangular area within a BitMap to new dimensions (V36). 



H ardwar e Programm i ng Funct i ons 



Descript i on 



OwnB li tt e r() 



Obta i n e xc l usiv e acc e ss to th e Am i ga's hardwar e b li tt e r. 



DisownBlitter() 
WaitBlit() 
QBIit() 
QBSBIit() 

CINIT() 

CWAIT() 

CMOVE() 

CBump() 

CENDQ 



Relinquish exclusive access to the blitter 

Suspend until the current blitter operation has completed. 

Place a bltnode-style asynchronous blitter request in the system queue 

Place a bltnode-style asynchronous blitter request in the beam synchronized 

queue. 

Initialize the user Copper list buffer. 

Instructs the Copper to wait for the video beam to reach a given position 

Instructs the Copper to place a value into a given hardware register. 

Instructs the Copper to increment its Copper list pointer. 

Terminate the user Copper list. 
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Chapter 28 

GRAPHICS SPRITES, BOBS 
AND ANIMATION 



This chapter describes how to use the functions provided by the graphics library to manipulate and animate 
Graphic Elements (also called GELs). It is divided into six sections: 

An overview of the GELs animation system, including fundamental terms and structures 

Explanation of simple (hardware) Sprites and an example showing their usage 

Explanation of VSprites and an example showing their usage 

Explanation of Bobs and an example showing their usage 

Discussion of topics that apply to all GELs such as collision detection and data structure extensions. 

Discussion of animation, using AnimComps and AnimObs and an example showing their usage 

About the GELs System 

Before going into details, a quick glossary is in order. A playfield forms the background that GELs operate 
in. It encompasses the View, ViewPort, and RastPort data structures. (VSprites appear over, and Bobs 
appear in the playfield.) Playfields can be created and controlled at several levels. Refer to the "Graphics 
Primitives" and "Layers Library" chapters for details on lower-level playfield control. The "Intuition 
Screens" chapter explains how to get higher-level access to playfields. 

GELs, or graphic elements, are special graphic objects that appear in the foreground and can be moved 
easily around the display. They are software constructs based on the Amiga's sprite and blitter hardware. 
The GELs system is compatible with all playfield modes, including dual-playfield. All the various types of 
GELs are defined by data structures found in <graphics/gels.h>. 

Graphics Sprites, Bobs and Animation 613 



TYPES OF GELS 

The GEL types are (in order of increasing complexity): 



VSprites for Virtual Sprites. These are represented by the VSprite data structure and 
implemented with sprite hardware. 

Bobs Blitter Objects. These are represented by the VSprite and Bob data structures and 

implemented with blitter hardware. 

AnimComps Animation Components. These are represented by the VSprite, Bob and 
AnimComp data structures and implemented with blitter hardware. 

AnimObs Animation Objects. These are used to group AnimComps. They are not strictly 

GELs, but are described here. 



Simple Sprites 

Simple Sprites (also known as hardware sprites) are not really part of the GELs system but are the basis for 
VSprites. Simple Sprites are graphic objects implemented in hardware that are easy to define and easy to 
animate. The Amiga hardware has the ability to handle up to eight such sprite objects. Each Simple Sprite is 
produced by one of the Amiga's eight sprite DMA channels. They are 16-bits wide and arbitrarily tall. 

The Amiga system software offers a choice of how to use these hardware sprites. After a sprite DMA channel has 
displayed the last line of a Simple Sprite, the system can reuse the channel for a different sprite lower on the 
screen. This is how VSprites are implemented-as a software construct based on the sprite hardware. 

Hence, Simple Sprites are not really part of the animation system (they are nor GELs). In fact, if SimpleSprites 
and GELs are used in the same display, the GELs system must be told specifically which Simple Sprites to avoid. 
Simple Sprites are described in this chapter because they are alternatives to VSprites. 

VSprites 

The VSprite, or virtual sprite, is the simplest type of GEL. The VSprite data structure contains just a bit more 
information than is needed to define a hardware sprite. VSprites take advantage of the system's ability to reuse 
sprite DMA channels-each VSprite can be temporarily assigned to a hardware sprite, as needed. This makes it 
appear to an application program that it has a virtually unlimited supply of VSprites. 

Since VSprites are based on hardware sprites, rules that apply to hardware sprites apply to VSprites too. 
VSprites are not rendered into the underlying BitMap of the playfield and so do not affect any bits in the BitMap. 
Because they are hardware based, they are positioned at absolute display coordinates and are not affected by 
the movement of screens. The starting position of a sprite must not occur before scanline 20, 
because of certain hardware DMA time constraints. VSprites have the same size limitations as hardware sprites, 
they are 16-bits wide and arbitrarily tall. 

The VSprite data structure also serves as the root structure of more complex GEL types-Bobs and AnimComps. 
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Bobs and AnimComps 

Like VSprites, Bobs and AnimComps are graphics objects that make animation easier. They are rendered using 
the blitter. The blitter is a special Amiga hardware component used to move data quickly and efficiently, optionally 
performing logical operations as it does. It can be used to move any kind of data but is especially well suited to 
moving rectangular blocks of display data. 

It is important to keep in mind that Bobs and AnimComps are based on the blitter hardware while VSprites use 



the sprite hardware. However all three GEL types use the VSprite structure as their root data structure. The 
system uses pointers to link the VSprite, Bob and AnimComp structures, "extending" the VSprite structure to 
include all GEL types. 

Since Bobs and AnimComps are rendered with the blitter they actually change the underlying playfield BitMap. 
The BitMap area where the GEL is rendered can be saved. By moving the GEL to new locations in small 
increments while also saving and restoring the Bitmap as you proceed, you can create an animation effect. Bobs 
and AnimComps use the same coordinates as the playfield and can be any size. 

AnlmObs 

The AnimOb (Animation Object) is a data structure that is used to group one or more AnimComps for convenient 
movement. For example, an AnimOb could be created that consists of two AnimComps, one that looks like a 
planet and another containing a sequence that describes orbiting moons. By moving just the AnimOb the image 
of the planet can be moved across the display and the moons will travel along with it, orbiting the planet the entire 
time. The system automatically manages the movement of all the AnimComps associated with the AnimOb. 

VSprites vs. Bobs 

If you are going to manage the movement and sequencing of GELS yourself, you need to decide if sprite 
animation (VSprites) or blitter animation (Bobs, AnimComps and AnimObs) best suit your needs. If you've got 
simple requirements or lots of coding time, you may even opt to use only Simple Sprites, and control them 
yourself. On the other hand if you want the system to manage your animations, AnimComps must be used and 
they are Bobs at heart. 

Some fundamental differences between VSprites and Bobs are: 

VSprite images and coordinates currently low-resolution pixels, even on a high resolution display. Bob 
images and coordinates have the same resolution as the playfield they are rendered into. 

VSprites have a maximum width of 16 (low resolution) pixels. Bobs can be any width (although large 
Bobs tend to slow down the system). The height of either VSprites or Bobs can be as tall as the display. 

VSprites have a maximum of three colours (Simple Sprites can have fifteen if they're attached). Because 
the system uses the Copper to control VSprite colours on the fly, the colours are not necessarily the 
same as those in the background playfield. Bobs can use any or all of the colours in the background 
playfield. Limiting factors include playfield resolution and display time. Bobs with more colours take 
longer to display. 

VSprites are positioned using absolute display coordinates, and don't move with screens. Bobs follow 
screen movement. 
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In general, VSprites offer speed, while Bobs offer flexibility. 

The following figure shows how the various GEL data structures, VSprites, Bobs and AnimComps are linked 
together. 
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Figure 28-1 : GEL Structure Layout 



THE GELS SYSTEM 



Before you can use the GELs system, you must set up a playfield. The GELs system requires access to a View, 
ViewPort, and RastPort structure. These structures may be set up through the graphics library or Intuition. For 
most examples in this chapter, the Intuition library is used for this purpose. 

All GELs have a VSprite structure at their core. The system keeps track of all the GELs that it will display (the 
active GELs) by using a standard Exec list structure to link the VSprites. This list is accessed via the Gelslnfo 
data structure, which in turn is associated with the RastPort. The Gelslnfo structure is defined in the file 
<graphics/rastport.h>. 

A new GEL is introduced to the system by calling AddGel() to link it into the Gelslnfo list. The new GEL is added 
immediately ahead of the first existing GEL whose x, y value is greater than or equal to that of the new GEL, 
always trying to keep the list sorted. 

As GELs are moved about the screen, their x, y values are constantly changing. SortGList() re-sorts this list by 
the x, y values. (Although this is a list of VSprite structures, bear in mind that some or all may really be Bobs or 
AnimComps.) 

The basic set up of the Gelslnfo structure requires three important fields: sprRsrvd, gelHead and gelTail. The 

sprRsrvd field tells the system which hardware sprites not to use when managing true VSprites. For instance, 
Intuition uses sprite for the mouse pointer so this hardware sprite is not available for assignment to a VSprite. 
The gelHead and gelTail are VSprite structures that are used to manage the list of GELs. They are never 
displayed. To activate or deactivate a GEL, a system call is made to add it to or delete it from this list. 
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Other fields must be set up to provide for collision detection, colour optimization, and other features. A complete 
example for setting up the Gelslnfo structure is shown in the animtools.c listing at the end of this chapter. 



Initializing the GEL System 

To initialize the animation system, call the system function InitGelsQ. It takes the form: 



struct VSprite *vsHead; 
struct VSprite *vsTail; 
struct Gelslnfo *gInfo; 

InitGels (vsHead, vsTail, glnfo); 

The vsHead argument is a pointer to the VSprite structure to be used as the GEL list head. (You must allocate 
an actual VSprite structure for vsHead to point to.) The vsTail argument is a pointer to the VSprite structure to 
be used as the GEL list tail. (You must allocate an actual VSprite structure for vsTail to point to.) the glnfo 
argument is a pointer to the Gelslnfo structure to be initialized. 

lnitGels() forms these structures into a linked list of GELs that is empty except for these two dummy elements 
(the head and tail). It gives the head VSprite the maximum negative x and y positions and the tail VSprite the 
maximum positive x and y positions. This is to aid the system in keeping the list sorted by x, y values, so GELs 
that are closer to the top and left of the display are nearer the head of the list. The memory space that the 
VSprites and Gelsinfo structures take up must already have been allocated. This can be done either by 
declaring them statically or explicitly allocating memory for them. 

Once the Gelslnfo structure has been allocated and initialized, GELs can be added to the system. Refer to the 
setupGelSys() and cleanupGelsys() functions in the animtools.c listing at the end of the chapter for examples of 
allocating, initializing and freeing a Gelslnfo structure. 

Using Simple (Hardware) Sprites 

Simple Sprites can be used to create animations, so even though are not really part of the GELs system, they are 
described here as a possible alternative to using VSprites. For more information on the sprite hardware, including 
information on attached sprites, see the Amiga Hardware Reference Manual. 

The SimpleSprite structure is found in <graphicslsprite.h>. It has fields that indicate the height and position of 
the Simple Sprite and a number that indicates which of the 8 hardware sprites to use. 

Simple Sprites are always 16 bits wide, which is why there is no width member in the SimpleSprite structure. 
Currently, sprites always appear as low-resolution pixels, and their position is specified in the same way. If the 
sprite is being moved across a high-resolution display in single pixel increments, it will appear to move two 
high-resolution pixels for each increment. In low-resolution mode, a single Lores pixel movement will be seen. 
Similarly, in an interlaced display, the y direction motions are in two-line increments. The same sprite image data 
is placed into both even and odd fields of the interlaced display, so the sprite will appear to be the same size in 
any display mode. 

The upper left corner of the ViewPort area has coordinates (0,0). Unlike VSprites, the motion of a Simple Sprite 
can be relative to this position. (That is, if you create a Simple Sprite relative to your ViewPort and move the 
ViewPort around, the Simple Sprite can move as well, but its movement is relative to the origin of the ViewPort.) 



Graphics Sprites, Bobs and Animation 617 



The Sprite pairs 0/I, 2/3, 4/5, and 617 share colour registers. See "VSprite Advanced Topics" later in this chapter, 
for precautions to take if Simple Sprites and VSprites are used at the same time. 

The following figure shows which colour registers are used by Simple Sprites. 
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Figure 28-2: Sprite Color Registers 

Sprites do not have exclusive use of the Colour registers. If the ViewPort is 5 bitplanes deep, all 32 of the system 
Colour registers will still be used by the playfield display hardware. 

Note: Colour zero for all Sprites is always a "transparent" Colour, and the colours in registers 
16, 20, 24, and 28 are not used by sprites. These colours will be seen only if they are 
rendered into a playfield. For further information, see the Amiga Hardware Reference 
Manual. 

If there are two Viewports with different Colour sets on the same display, a sprite will switch colours when it is 
moved across their boundary. For example, Sprite and 1 will appear in colours 1 7-1 9 of whatever ViewPort 
they happen to be over. This is because the system jams all the Viewports colours into the display hardware at 
the top of each ViewPort. 
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SIMPLE SPRITE FUNCTIONS 



There are four basic functions that you use to control Simple Sprites: 

GetSprite() Attempts to allocates a sprite for exclusive use 

ChangeSprite() Modifies a Simple Sprite's image data 

MoveSprite() Changes a Simple Sprite's position 

FreeSprite() Relinquishes a sprite so it can be used by others 

To use these Simple Sprite functions (or the VSprite functions) the SPRITE flag must have been set in the 
NewScreen structure for OpenScreen(). If Intuition is not being used, this flag must be specified in the View and 
ViewPort data structures before MakeVPort() is called. 



Accessing A Hardware Sprite 

GetSprite() is used to gain exclusive access to one of the eight hardware sprites. Once you have gained control 
of a hardware sprite, it can no longer be allocated by the GELs system for use as a VSprite. The call is made like 
this: 

struct SimpleSprite *sprite; 
SHORT number; 

if (-1 == (sprite_num = GetSprite (sprite, number))) 

return_code = RETURN_WARN; /* did not get the sprite */ 

The inputs to the GetSprite() function are a pointer to a SimpleSprite structure and the number (0-7) of the 
hardware sprite to be accessed, or -1 to get the first available sprite. 

A value of 0-7 is returned if the request was granted, specifying which sprite was allocated. A returned value of -1 
means the requested sprite was not available. If the call succeeds, the SimpleSprite data structure will have its 
sprite number field filled in with the appropriate number. 

Changing The Appearance Of A Simple Sprite 

The ChangeSprite() function can be used to alter the appearance of a Simple Sprite. ChangeSpriteQ 
substitutes new image data for the data currently used to display a Simple Sprite. It is called by the following 
sequence: 

struct Viewport *vp; 
struct SimpleSprite *sprite; 
APTR newdata; 

ChangeSprite (vp, sprite, newdata); 

The vp input to this function is a pointer to the ViewPort for this Sprite or if this Sprite is relative only to the 
current View. The sprite argument is a pointer to a SimpleSprite data structure. (You must allocate an actual 
SimpleSprite structure for sprite to point to.) Set newdata to the address of an image data structure containing 
the new image. The data must reside in Chip (MEMF_CHIP) memory. 
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The structure for the new sprite image data is shown below. It is not a system structure, so it will not be found in 
the system includes, but it is described in the documentation for the ChangeSpriteQ call. 

struct spriteimage 
( 
UWORD posctl[2] ; /* position and control data for this Sprite */ 

/* Two words per line of Sprite height, first of the two words contains the MSB for 

* color selection, second word contains LSB (colors 0,1,2,3 from allowable color 

* register selection set) . Color '0' for any Sprite pixel makes it transparent. 

*/ 

UWORD data [height] [2]; /* actual Sprite image */ 

UWORD reserved [2] ; /* reserved, initialize to 0, */ 

}; 

Moving A Simple Sprite 

MoveSprite() repositions a Simple Sprite. After This function is called, the Simple Sprite is moved to a new 
position relative to the upper left corner of the ViewPort. It is called as follows: 



struct ViewPort *vp; 
struct SimpleSprite *sprite; 



SHORT x, y; 

MoveSprite (vp, sprite, x, y) ; 

There are three inputs to MoveSpriteQ. Set the vp argument to the address of the ViewPort with which this 
Simple Sprite interacts or if this Simple Sprite's position is relative only to the current View. Set sprite to the 
address of your SimpleSprite data structure. The x and y arguments specify a pixel position to which the Simple 
Sprite is to be moved. 

Relinquishing A Simple Sprite 

The FreeSprite() function returns a hardware sprite allocated with GetSprite() to the system so that GELs or 
other tasks can use it. After you call FreeSprite(), the GELs system can use it to allocate VSprites. The syntax of 
this function is: 

WORD sprite_number ; 

FreeSprite (sprite_number) ; 

The sprite_number argument is the number (0-7) of the sprite to be resumed to the system. 

Controlling Sprite DMA 

Two additional functions used with Simple Sprites are the graphics library macros ON_SPRITE and 
OFF_SPRITE. These macros can be used to control sprite DMA. OFF_SPRITE prevents the system from 
displaying any sprites, whether Simple Sprites or VSprites. ON_SPRITE restores the sprite display. 

Be Careful With OFFSPRITEThe Intuition mouse pointer is a sprite. Thus, if 
OFF_SPRITE\s used, Intuition's pointer will disappear too. Use care when calling 
OFFSPRITE. The macro turns off sprite fetch DMA, so that no new sprite data is 
fetched. Whatever sprite data was last being displayed at this point will continue to be 
displayed for every line on the screen. This may lead to a vertical Colour bar if a sprite is 
being displayed when OFFSPRITE is called. 
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Complete Simple Sprite Example 

The following example demonstrates how to set up, move and free a Simple Sprite. The animtools.h file included 
is listed at the end of the chapter. 

/* ssprite.c - Simple Sprite example 
* * 

** SAS/C V5 .10a 

** lc -bl -cfist -v -y ssprite.c 

** blink FROM LIB:c,o ssprite.o LIB LIB :1c. lib LIB : amiga . lib TO ssprite 

*/ 

#lnclude <exec/types . h> 
#include <graphics/gfx.h> 
#include <graphics/gfxbase . h> 
#include <graphics/gfxmacros . h> 
#include <qraphics/sprite . h> 
#include <intuition/intuitionbase . h> 
#include <intuition/screens . h> 
#include <hardware/custom.h> 
#include <hardware/dmabits . h> 
#include <libraries/dos . h> 

#include <clib/graphics_protos . h> 
#include <clib/exec_protos . h> 
#include <clib/intuition_protos . h> 
#include <clib/alib stdio protos.h> 



1 


*/ 


1 


*/ 


2 


*/ 


2 


*/ 



#include <stdlib.h> 

struct Gf xBase *Gf xBase = NULL; 

struct IntuitionBase *IntuitionBase = NULL; 

extern struct Custom far custom ; 

/* real boring sprite data */ 
UWORD chip sprite_data [ ] = 

{ 

0,0, /* position control */ 

0-xffff, 0x0000, /* image data line 1, colour 

Oxffff, 0x0000, /* image data line 2, colour 

0x0000, Oxffff, /* image data line 3, colour 

0x0000, Oxffff, /* image data line 9, colour 

0x0000, 0x0000, /* image data line 5, transparent */ 

0x0000, Oxffff, /* image data line 6, colour 2 */ 

0x0000, Oxffff, /* image data line 7, colour 2 */ 

Oxffff, Oxffff, /* image data line 8, colour 3 */ 

Oxffff, Oxffff, /* image data line 9, colour 3 */ 

0, /* reserved, must init to */ 

}; 

VOID main(int argc, char **argv) 

{ 

struct SimpleSpritesprite = {Ob- 
struct Viewport * viewport ; 
WORD sprite_num; 

SHORT delta_move, ktrl, ktr2, colour_reg; 
struct Screen *screen; 
int return code; 

return code = RETURN OK; 

if (NULL == (GfxBase = (struct GfxBase *) OpenLibrary ( "graphics . library" , 37L) ) ) 

returncode = RETURN_FAIL; 
else 

{ 

if (NULL = = (IntuitionBase = (struct IntuitionBase 
*) OpenLibrary ( "intuition. library" , 37L) ) ) 
returncode = RETURN_FAIL; 
else 

{ 

/* opened library, need a viewport to render a sprite over. */ 
if (NULL == (screen = OpenScreenTagList (NULL, NULL))) 

returncode = RETURN_FAIL; 
else 

{ 

viewport = &screen->ViewPort ; 
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if (-1 == (sprite_num - GetSprite (ssprite, 2))) 

return code - RETURN_WARN; 
else 

{ 

/* Calculate the correct base colour register number, */ 

/* set up the colour reqlsters. */ 

colourreq - 16 + ( (sprite_num s 0x06) << 1) ; 

printf ( "colour reg-%d\n", colourreq) ; 

SetRGB4 (viewport, colour reg + 1, 12, 3, 8) ; 

SetRGB4 (viewport, colour req +2, 13, 13, 13); 

SetRGB4 (viewport , colour reg + 3, 4, 4, 15); 

sprite. x =0; /* initialize position and size info */ 
sprite. y =0; /* to match that shown in sprite_data */ 
sprite .heiqht -9; /* so system knows layout of data later */ 

/* install sprite data and move sprite to start position. */ 
ChanqeSprite (NULL, ssprite, (APTR) sprite_data) ; 
MoveSprite (NULL, Ssprite, 30, 0); 



/* move the sprite back and forth. */ 

for ( ktrl = 0, delta_move = 1; ktrl < 6; ktrl++, delta move = -delta move) 

{ 

for ( ktr2 = 0; ktr2 < 100; ktr2++) 

{ 

MoveSprite ( NULL, ssprite, (LONG) (sprite. x + delta_move), 

(LONG) (sprite. y + delta_move) ) ; 
WaitTOFO ; /* one move per video frame */ 

/* Show the effect of turninq off sprite DMA. */ 
if (ktr2 == 40) OFF_SPRITE ; 
if (ktr2 == 60) ON SPRITE ; 
} 
} 

/* NOTE: if you turn off the sprite at the wrong time (when it 

** is beinq displayed) , the sprite will appear as a vertical bar 

** on the screen. To really get rid of the sprite, you must 

** OFF_SPRITE while it is not displayed. This is hard in a 

** multi-tasking system (the solution is not addressed in 

** this proqram) . 
*/ 

ON_SPRITE ; /* just to be sure */ 

FreeSprite ( (WORD) sprite_num) ; 

} 

(VOID) CloseScreen (screen) ; 

} 

CloseLibrary ( (struct Library *) IntuitionBase) ; 

} 

CloseLibrary ( (struct Library *)Gf xBase); 

} 

exit (return code); 

} 



Using Virtual Sprites 



This section describes how to set up the VSprite structure so that it represents a true VSprite. True VSprites are 
managed by the GELs system which converts them to Simple Sprites and displays them. (Later sections describe 
how a VSprite structure can be set up for Bobs and AnimComps.) 

Before the system is told of a VSprite's existence, space for the VSprite data structure must be allocated and 
initialized to correctly represent a VSprite. Since the system does no validity checking on the VSprite structure, 
the result of using a bogus structure is usually a fireworks display, followed by a system failure. 

The system software provides a way to detect collisions between VSprites and other on-screen objects. There is 
also a method of extending the VSprite structure to incorporate user defined variables. These subjects are 
applicable to all GELs and are explained later in "Collisions and GEL Structure Extensions". 
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SPECIFICATION OF VSPRITE STRUCTURE 

The VSprite structure is defined in the include file <graphics/gels.h> as follows: 

/* VSprite structure definition */ 
struct VSprite { 

struct VSprite *Next VSprite; 

struct VSprite *PrevVSprite; 

struct VSprite *DrawPath; 

struct VSprite *ClearPath; 

WORD OldY, OldX; 



WORD 




Flags ; 


WORD 




Y, X; 


WORD 




Height; 


WORD 




Width; 


WORD 




Depth; 


WORD 




MeMask; 


WORD 




HitMask; 


WORD 




*ImageData; 


WORD 




*BorderLine 


WORD 




*CollMask; 


WORD 




*SprColours 


struct 


Bob 


*VSBob; 


BYTE 




PlanePick; 


BYTE 




PlaneOnOf f ; 


VUserStuff 


VUserExt 



There are two primary ways to allocate and fill in space for VSprite data. They can be statically declared, or a 
memory allocation function can be called and they can be filled in programmatically. The declaration W statically 
set up a VSprite structure is listed below. 

/* VSprite static data definition. 

** must set the following for TRUE VSprites : 

** VSPRITE flag. 

** Width to 1. 

** Depth to 2. 

** VSBob to NULL. 



struct VSprite myVSprite 
{ 



}, 



NULL, NULL, NULL, NULL, 0, 0, VSPRITE, 0, 0, 5, 1, 2, 0, 0, 
&mylmage, 0, 0, kmySpriteColours, NULL, 0x3, 0, 



This static allocation gives the required VSprite structure, but does not allocate or set up collision mask for the 
VSprite. Note that the VSprite structure itself does not need to reside in Chip memory. 

Refer to the makeVSprite() and freeSpriteQ functions in the animtools.c listing at the end of the chapter an 
example of dynamically allocating, initializing and freeing a VSprite structure. 



RESERVED VSPRITE MEMBERS 

These VSprite structure members are reserved for system use (do not write to them): 



NextVSprite() and PrevVSprite 
DrawPath() and ClearPath 
OldY and OldX 



These are used as links in the Gelslnfo list. 
These are used for Bobs, not true VSprites. 
Previous position holder, the system uses these for double buffered 
Bobs, but application programs can read them too. 



The values can be set like this: 
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myVSprite. NextVSprite = NULL; 
myVSprite . PrevVSprite = NULL; 
myVSprite. DrawPath = NULL; 
myVSprite. ClearPath = NULL; 
myVSprite. OldY = 0; 
myVSprite. OldX = 0; 



USING VSPRITE FLAGS 

The Flags member of the VSprite structure is both read and written by the system. Some bits are used by the 
application to inform the system; others are used by the system to indicate things to the application. 

The only Flags bits that are used by true VSprites are: 

VSPRITE 
This may be set to indicate to the system that it should treat the structure as a true VSprite, not part of a Bob. 
This affects the interpretation of the data layout and the use of various system variables. 

VSOVERFLOW 
The system sets this bit in the true VSprites that it is unable to display. This happens when there are too many 
in the same scan line, and the system has run out of Simple Sprites to assign. It indicates that this VSprite has 
not been displayed. If no sprites are reserved, this means that more than eight sprites touch one scan line. This 
bit will not be set for Bobs and should not be changed by the application. 

GELGONE 
If the system has set GELGONE bit in the Flags member, then the GEL associated with this VSprite is not on 
the display at all, it is entirely outside the GEL boundaries. This area is defined by the Gelslnfo members 
topmost, bottommost, leftmost and rightmost (see <graphics/rastport.h>). On the basis of that information, 
the application may decide that the object need no longer be part of the GEL list and may decide to remove it to 
speed up the consideration of other objects. Use RemVSprite() (or RemBob(), if it's a Bob) to do this. This bit 
should not be changed by the application. 

The VSprite.Flags value should be initialized like this for a VSprite GEL: 

myVSprite.Flags =VSPRITE; 

VSPRITE POSITION 

To control the position of a VSprite, the x and y variables in the VSprite structure are used. These specify where 
the upper left corner of the VSprite will be, relative to the upper left corner of the playfield area it appears over. So 
if VSprites are used under Intuition and within a screen, they will be positioned relative to the upper left-hand 
corner of the screen. 

In a 320 by 200 screen, a y value of puts the VSprite at the top of that display, a y value of (200 - VSprite 
height) puts the VSprite at the bottom. And an x value of puts the VSprite at the left edge of that display, while 
an x value of (320 - VSprite width) puts the VSprite at the far right. Values of less than (0,0) or greater than (320, 
200) may be used to move the VSprite partially or entirely off the screen, if desired. 
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See the "Graphics Primitives" chapter for more information on display coordinates and display size. See the 
Amiga Hardware Reference ManuaHor more information on hardware sprites. 

Position VSprites Properly. It is important that the starting position of true VSprites is not 
less than -20 in the y direction, which is the start of the active display area for sprites. 
Also, if they are moved too far to the left, true VSprites may not have enough DMA time 
to be displayed. 

The x, y values may be set like this to put the VSprite in the upper-left: 

myVSprite.Y = 0; 
myVSprite.X = ; 

VSPRITE IMAGE SIZE 

A true VSprite is always one word (16 pixels) wide and may be any number of lines high. It can be made to 



appear thinner by making some pixels transparent. Like Simple Sprites, VSprite pixels are always the size of a 
pixel in low-resolution mode (320x200); regardless of the resolution the display is set to. To specify how many 
lines make up the VSprite image, the VSprite structure member, Height, is used. VSprites always have a Depth 
of two, allowing for three colours. The values may be set like this: 

myVSprite. Width =1; /* ALWAYS 1 for true VSprites. */ 
myVSprite .Height =5; /* The example height. */ 
myVSprite. Depth = 2; /* ALWAYS 2 for true VSprites. */ 

VSPRITES AND COLLISION DETECTION 

Some members of the VSprite data structure are used for special purposes such as collision detection, user 
extensions or for system extensions (such as Bobs and AnimComps). For most applications these fields are set 
to zero: 

myVSprite .HitMask =0; /* These are all used for collision detection */ 

myVSprite. MeMask = ; 
myVSprite .BorderLine = 0; 
myVSprite. CollMask = 0; 

myVSprite .VUserExt =0; /* Only use this for user extensions to VSprite */ 

myVSprite .VSBob = NULL; /* Only Bobs and AnimComps need this */ 

The special uses of this fields are explained further in the sections that follow. 

VSPRITE IMAGE DATA 

The ImageData pointer of the VSprite structure must be initialized with the address of the first word of the image 
data array. The image data array must be in Chip memory. It takes two sequential 16-bit words to define each 
line of a VSprite. This means that the data area containing the VSprite image is always Height x 2 (10 in the 
example case) words long.. 

A VSprite image is defined just like a real hardware sprite. The combination of bits in corresponding locations in 
the two data words that define each line select the colour for that pixel. The first of the pair of words supplies the 
low-order bit of the colour selector for that pixel; the second word supplies the high-order bit. 
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These binary values select colours as follows: 

00 - selects "transparent" 
01- selects the first of three VSprite colours 
10 - selects the second VSprite colour 
11- selects the third VSprite colour 

In those areas where the combination of bits yields a value of 0, the VSprite is transparent. This means that the 
playfield, and all Bobs and AnimComps, and any VSprite whose priority is lower than this VSprite will all show 
through in transparent sections. For example: 

(&VSprite->lmageData) 1 01 0000 0000 0000 

(&VSprite->lmageData+ 1 ) 0110 0000 0000 0000 

Reading from top to bottom, left to right, the combinations of these two sequential data words form the binary 
values of 01,10,11, and then all OOs. This VSprite's first pixel will be colour I, the next colour 2, the third colour 3. 
The rest will be transparent, making this VSprite appear to be three pixels wide. Thus, a three-colour image, with 
some transparent areas, can be formed from a data set like the following sample: 



Address 

mem 
mem + 1 


Binary Data 

1111 1111 1111 1111 
1111 1111 1111 1111 


VSprite Image Data 

Defines top line 
3333 3333 3333 3333 


mem + 2 
mem + 3 


0011 1100 0011 1100 
0011 0000 0000 1100 


Defines second line 
00331100 0011 3300 


mem + 4 
mem + 5 


0000 1100 0011 0000 
0000 1111 1111 0000 


Defines third line 
0000 3322 2233 0000 


mem + 6 
mem + 7 


0000 0010 0100 0000 
0000 0011 1100 0000 


Defines fourth line 
0000 0032 2300 0000 


mem + 8 
mem + 9 


0000 0001 1000 0000 
0000 0001 1000 0000 


Defines fifth line 
0000 0003 3000 0000 



The VSprite.Height for this sample image is 5. 



SPECIFYING THE COLOURS OF A VSPRITE 

The system software provides a great deal of versatility in the choice of colours for Virtual Sprites. Each VSprite 
has its own sef of three colours, pointed to by SprColors, which the system jams into the display's Copper list as 
needed. 

SprColors points to the first of three 16-bit values. The first value represents the colour used for the VSprite bits 
that select colour 1 , the second value is colour 2, and the third value is colour 3. When the system assigns a 
hardware sprite to carry the VSprite's image, it jams these colour values into the Copper list (the intermediate 
Copper list, not the colour table), so that the View's colours will be correct for this VSprite at the time the VSprite 
is displayed. It doesn't jam the original palette's colours back after the VSprite is done. If there is another VSprite 
later, that VSprite's colours will get jammed; if there is not another VSprite, the colours will remain the same until 
the next Viewport's colours get loaded. 
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If the SprColors pointer is set to NULL, that VSprite does not generate a colour-change instruction stream for the 
Copper. Instead, the VSprite appears drawn in whatever colour set that the hardware sprite happens to have in it 
already. 

Since the registers are initially loaded with the colours from the Viewport's ColorMap, if all VSprites have NULL 
SprColors, they will appear in the Viewport's colours. 

To continue our example, a set of colours can be declared and the VSprite colours set with the following 
statements: 

WORD mySpriteColours [} = { 0x0000, OxOOfO, OxOfOO } ; /* Declare colours statically */ 
myVSprite . SprColours = mySpriteColours; /* Assign colours to VSprite */ 

ADDING AND REMOVING VSPRITES 

Once a true VSprite has been set up and initialized, the obvious next step is to give it to the system by adding it 
to the GEL list. The VSprite may then be manipulated as needed. Before the program ends, the VSprite should 
be removed from the GELs list by calling RemVSprite(). A typical calling sequence could be performed like sa: 

struct VSprite myVSprite = {Ob- 
struct RastPort myRastPort = {o}; 



AddVSprite (kmyVSprite, kmyRastPort) ; 

/* Manipulate the VSprite as needed here */ 



RemVSprite (&myVSprite) ; 

The &myVSprite argument is a fully initialized VSprite structure and SmyRastPort is the RastPort with which 
this VSprite is to be associated. Note that you will probably not like the results if you try to RemVSpriteQ a 
VSprite that has not been added to the system with AddVSpriteQ. See the Amiga ROM Kernel Reference 
Manual: Includes and Autodocs for additional information on these functions. 



CHANGING VSPRITES 

Once the VSprite has been added to the GELs list and is in the display, some of its characteristics can be 
changed dynamically by: 

Changing y, x to a new VSprite position 

Changing ImageData to point to a new VSprite image 

Changing SprColors to point to a new VSprite colour set 

Study The next two sections to find out how to reserve hardware Sprites for use outside the VSprite system and 
how to assign the VSprites. 
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GETTING THE VSPRITE LIST IN ORDER 

When the system has displayed the last line of a VSprite, it is able to reassign the hardware sprite to another 
VSprite located at a lower position on the screen. The system allocates hardware sprites in the order in 
which it encounters the VSprites in the list. Therefore, the list of VSprites must be sorted before the system can 
assign the use of the hardware Sprites correctly. 

The function SortGList() must be used to get the GELs in the correct order before the system is asked to 
display them. This sorting step is essential! It should be done before calling DrawGList(), whenever a GEL has 
changed position. This function is called as follows: 

struct RastPort myRastPort = (0); 
SortGList (kmyRastPort) ; 

The only argument is a pointer to the RastPort structure containing the Gelslnfo. 

DISPLAYING THE VSPRITES 

The next few sections explain how to display the VSprites. The following system functions are used: 

DrawGList() Draws the VSprites into the current RastPort. 

MrgCop() Installs the VSprites into the display. 

LoadView() Asks the system to display the new View. 

WaitTOF() Synchronizes the functions with the display. 

Drawing the Graphics Elements 

The system function called DrawGListQ looks through the list of GELS and prepares the necessary Copper 
instructions and memory areas to display the data. This function is called as follows: 

struct RastPort myRastPort = {Ob- 
struct Viewport myViewPort = {o}; 

DrawGList (&myRastPort , kmyViewPort) ; 

The myRastPort argument specifies the RastPort containing the Gelslnfo list with the VSprites that you 
want to display. The SmyViewPort argument is a pointer to the ViewPort for which the VSprites will be 



created. 



Merging VSprite Instructions 

Once DrawGList() has prepared the necessary instructions and memory areas to display the data, the 
VSprites are installed into the display with MrgCop(). (DrawGList() does not actually draw the VSprites, it only 
prepares the Copper instructions.) 

struct View *view; 

MrgCop (view) ; 

The view is a pointer to the View structure whose Copper instructions are to be merged. 
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Loading the New View 

Now that the display instructions include the definition of the VSprites, the system can display this newly 
configured View with the LoadView() function: 

struct View *view; 

LoadView (view) ; 

Again, view is a pointer to the View that contains the new Copper instruction list (if you are using GELs in an 
Intuition Screen, do not call LoadView().) 

The Copper instruction lists are double-buffered, so this instruction does not actually take effect until the next 
display field occurs. This avoids the possibility of some function trying to update the Copper instruction list while 
the Copper is trying to use it to create the display. 

Synchronizing with the Display 

To synchronize application functions with the display, call the system function WaitTOFQ. WaitTOF() holds your 
task until the vertical-blanking interval (blank area at the top of the screen) has begun. At that time, the system 
has retrieved the current Copper instruction list and is ready to allow generation of a new list. 

WaitTOFO ; 

WaitTOFQ takes no arguments and returns no values. It simply suspends your task until the video beam is at the 
top of field. 



Complete VSprite Example 



The listing given here shows a complete VSprite example. This program requires the animtools.c, animtools.h 
and animtools_proto.h support files in order to compile and run. These files are listed at the end of this chapter. 

/* vsprite.c 
* * 

** SAS/C V5 .10a 

** lc -bl -cfist -v -y vsprite.c 

** blink FROM LIBic.o vsprite . o animtools.o LIB LIB :1c. lib LIB : amiga . lib TO vsprite 

*/ 

#include <exec/types .h> 

#include <exec/memory . h> 

#include <intuition/intuitionbase . h> 

#include <graphics/gfx.h> 



#include <graphics/gfxbase . h> 
#include <graphics/gels . h> 
#include <graphics/collide .h> 
#include <libraries/dos . h> 
#include <stdlib.h> 
#include "animtools .h" 

VOID borderCheck( struct VSprite *hitVSprite, LONG borderflags); 

VOID process_window( struct Window *win, struct RastPort *myRPort, struct VSprite *MyVSprite) ; 

VOID do_VSprite (struct Window *win, struct RastPort *myRPort) ; 

VOID vspriteDrawGList (struct Window *win, struct RastPort *myRPort) ; 

struct GfxBase*Gf xBase; /* pointer to Graphics library */ 

struct IntuitionBase *IntuitionBase; /* pointer to Intuition library */ 

Graphics Sprites, Bobs and Animation 629 

int return_code; 

#define GEL SIZE 9 /* number of lines in the vsprite */ 

/* VSprite data - there are two sets that are alternated between. */ 
/* note that this data is always displayed as low resolution. */ 

WORD chip vsprite_datal{ } = { 0x7ffe, OxBOff, 
0x7c3e, 0x803f, 

0x7c3e, 0x803f, 
0x7ffe, OxBOff, 

0, ) ; 

WORD chip vsprite_data2 [) = { 0x7ffe, OxffOl, 

0x7c3e, OxfcOl, 
0x7c3e, OxfcOl, 
0x7ffe, OxffOl, 
0,0 } ; 

WORD mySpriteColours ( } = { 0x0000, OxOOfO, OxOfOO }; 
WORD mySpriteAltColours{ } = { OxOOOf, OxOfOO, OxOffO }; 

NEWVSPRITE myNewVSprite =1 /* information for the new VSprite */ 

/* Image data, sprite colour array word width (must be 1 for true VSprite) */ 

vsprite_datal , mySpriteColours , 1 , 
/* Line height, image depth (must be 2 for true VSprite) , x, y position */ 

GEL_SIZE, 2, 160, 100, 
/* Flags (VSPRITE == true VSprite) , hit mask and me mask */ 

VSPRITE, 1 << BORDERHIT, 

}; 

struct NewWindow myNewWindow = /* information for the new window */ 

{ 

B0, 20, 900, 150, -1, -1, CLOSEWINDOW | INTUITICKS, 
ACTIVATE | WINDOWCLOSE | WINDOWDEPTH | RMBTRAP | WINDOWDRAG, 
NULL, NULL, "VSprite", NULL, NULL, 0, 0, 0, 0, WBENCHSCREEN 

}; 

/* Basic VSprite display subroutine */ 

VOID vspriteDrawGList (struct Window *win, struct RastPort *myRPort) 

{ 

SortGList (myRPort) ; 

DrawGList (myRPort, ViewPortAddress (win) ) ; 

RethinkDisplay ( ) ; 

} ; 

/* Collision routine for vsprite hitting border. Note that when the collision is VSprite to */ 
/* VSprite (or Bob to Bob, Bob to AnimOb, etc) , then the parameters are both pointers to a 
VSprite. */ 
VOID borderCheck (struct VSprite *hitVSprite, LONG borderflags) 

{ 

if (borderflags & RIGHTHIT) 

{ 

hitVSprite->SprColours = mySpriteAltColours; 



hitVSprite->VUserExt = -40; 
} 

if (borderflags & LEFTHIT) 

{ 

hitVSprite->SprColours = mySpriteColours; 

hitVSprite->VUserExt = 20; 
} 
} 

/* Process window and dynamically change vsprite. Get messages. Go away on */ 

/* CLOSEWINDOW. Update and redisplay vsprite on INTUITICKS. Wait for more messages. */ 

VOID process window(struct Window *win, struct RastPort *myRPort, struct VSprite *myVSprite) 

{ 

struct IntuiMessage *msg; 

FOREVER 

{ 

Wait(lL << win->UserPort->mp_SigBit) ; 

while (NULL != (msg = (struct IntuiMessage *) GetMsg (win->UserPort) ) ) 



{ 



/* Only CLOSEWINDOW and INTUITICKS are active */ 
if (msq->Class == CLOSEWINDOW) 

{ 

ReplyMsg ( (struct Message *)msg); 
return; 
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/* Must be an INTUITICKS: change x and y values on the fly. Note offset by 

* window left and top edge--sprite relative to the screen, not window. Divide 
* the MouseY in half to adjust for Lores movement increments on a Hires screen. 
*/ 

myVSprite->X = win->Lef tEdqe + msq->MouseX + myVSprite- >VUserExt; 
myVSprite->Y = win->TopEdge + msq->MouseY/2 + 1; 
ReplyMsg ( (struct Message ')msg); 

} 

/* Got a message, change image data on the fly */ 

myVSprite->ImageData = (myVSprite->ImaqeData == vsprite datal) ? vsprite data2 : vsprite 
datal; 

SortGList (myAPort) ; 

DoCollision (myRPort) ; 

vspriteDrawGList (win, myAPort); 
} 

/* Working with the VSprite. Setup the GEL system and get a new VSprite (makeVSprite ( ) ) . */ 
/* Add VSprite to the system and display. Use the vsprite. When done, remove VSprite and */ 
/* update the display without the VSprite. Cleanup everything. */ 
VOID do VSprite (struct Window 'win, struct RastPort *myRPort) 



{ 



struct VSprite*myVSprite; 
struct Gelslnf o*my_ginf o; 

if (NULL == (my_ginfo = setupGelSys (myRPort , Oxfc) ) ) 

returncode = RETURN WARN; 
else 

{ 

if (NULL == (myVSprite = makeVSprite (kmyNewVSprite) ) ) 
returncode = RETURN WARN; 
else 

{ 

AddVSprite (myVSprite, myRPort); 

vspriteDrawGList (win, myRPort); 

myVSprite- >VUserExt = 20; 

SetCollision(BORDERHIT, borderCheck, myRPort- >GelsInfo) 

processwindow (win, myRPort, myVSprite); 

RemVSprite (myVSprite) ; 

freeVSprite (myVSprite) ; 
} 



vspriteDrawGList (win, myRPort); 
cleanupGelSys (my ginfo, myRPort); 
} 

/' Example VSprite progzam. First open up the libraries and a window. */ 
VOID main(int argc, char ' *argv) 

{ 

struct Window *win; 

struct RastPort myRPort = {o}; 

return_code = RETURN_OK; 

if (NULL == (Gf xBase = (struct Gf xBase ' ) OpenLibrary (GRAPHICSNAME, 3 7L) ) ) 

returncode = RETURN_FAIL; 
else 

{ 

if (NULL == (IntuitionBase = (struct IntuitionBase *) OpenLibrary (INTUITIONNAME, 37L) ) ) 

return_code = RETURN_FAIL; 
else 

{ 

if (NULL == (win = OpenWindow (SmyNewWindow) ) ) 

returncode = RETURN_WARN; 
else 

{ 

InitRastPort (&myRPort) ; 

myRPort = win->WScreen->RastPort ; /* Copy the structure. */ 

do_VSprite (win, &myRPort) ; 

CloseWindow (win) ; 

} 

CloseLibrary ( (struct Library *) IntuitionBase) ; 

} 

CloseLibrary ( (struct Library *)GfxBase);. 

} 

exit (return code) ; 
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VSprite Advanced Topics 



This section describes advanced topics pertaining to VSprites. It contains details about reserving hardware 
sprites for use outside of the GELs VSprite system, information about how VSprites are assigned, and more 
information about VSprite colours. 

Reserving Hardware Sprites 

To prevent the VSprite system from using specific hardware sprites, set the sprRsrvd member of the Gelslnfo 
structure. The pointer to the Gelslnfo structure is contained in the RastPort structure. If all of the bits of this 8-bit 
value are ones (OxFF), then all of the hardware sprites may be used by the VSprite system. If any of the bits is a 
0, the sprite corresponding to that bit will not be utilized by VSprites. 

Reserving Can Cause Problems. Reserving sprites increases the likelihood of the system 
not being able to display a VSprite (VSOVERFLOW). See the next section, "How 
VSprites are Assigned," for further details on this topic. 

You reserve a sprite by setting its corresponding bit in sprRsrvd. For instance, to reserve sprite zero only, set 
sprRsrvd to 0x01 . To reserve sprite three only, set sprRsrvd to 0x09. 

If a hardware sprite is reserved, the system will not consider it when it makes VSprite assignments. Remember, 
hardware sprite pairs share colour register sets. If a hardware sprite is reserved, its mate should probably be 
reserved too, otherwise the reserved sprite's colours will change as the unreserved mate is assigned different 
VSprites. For example, it is common practice to reserve Sprites and 1 , so that the Intuition pointer (Sprite 0) is 
left alone. This could be accomplished with the following statements: 



struct RastPort myRastPort = {o}; /* the View structure is defined */ 

myRastPort .Gelslnf o->sprRsrvd = 0x03; /* reserve and 1 */ 

The GfxBase structure may be examined to find which sprites are already in use. This may, at your option, 
impact what sprites you reserve. If Intuition is running, sprite will already be in use as its pointer. 

The reserved sprite status is accessible as 

currentreserved = GfxBase ->SpriteReserved; 

The next section presents a few trouble-shooting techniques for VSprite assignment. 

How VSprltes Are Assigned 

Although VSprites are managed for you by the GELs system there are some underlying limitations which could 
cause the system to run out of VSprites. 

As the system goes through the GEL list during DrawGList(), whenever it finds a true VSprite, it goes through 
the following procedure. If there is a Simple Sprite available (after the reserved sprites and preceding VSprites 
are accounted for), Copper instructions are added that will load the sprite hardware with this VSprite's data at the 
right point on the screen. It may need to add a Copper instruction sequence to load the display's colours 
associated with the sprite as well. 
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There are only 8 real sprite DMA channels. The system will run out of hardware sprites if it is asked to display 
more than eight VSprites on one scan line. This limit goes down to four when the VSprites have different 
SprCoior pointers. During the time that there is a conflict, the VSprites that could not be put into Simple Sprites 
will disappear. They will reappear when (as the VSprites are moved about the screen) circumstances permit. 

These problems can be alleviated by taking some precautions: 

Minimize the number of VSprites to appear on a single horizontal line. 

If colours for some Virtual Sprites are the same, make sure that the pointer for each of the VSprite 
structures for these Virtual Sprites points to the same memory location, rather than to a duplicate set of 
colours elsewhere in memory. The system will know to map these into Sprite pairs. 

If a VSprite's SprColors are set to NULL, the VSprite will appear in the Viewport's ColorMap colours. The 
system will display the VSprite in any one of a set of four different possible colour groupings as indicated in the 
Simple Sprite section above. 

If SprColors points to a colour set, the system will jam SprColors into the display hardware (via the Copper list), 
effectively overriding those ColorMap registers. The values in the ColorMap are not overwritten, but anything in 
the background display that used to appear in the ColorMap colours will appear in SprColors colours. 

How VSprite and Playfield Colours Interact 

At the start of each display, the system loads the colours from the Viewport's colour table into the display's 
hardware registers, so whatever is rendered into the BitMap is displayed correctly. But if the VSprite system is 
used, and the colours are specified (via SprColors) for each VSprite, the SprColors will be loaded by the system 
into the display hardware, as needed. The system does this by generating Copper instructions that will jam the 
colours into the hardware at specific moments in the display cycle. Any BitMap rendering, including Bobs, which 
share colours with VSprites, may change colours constantly as the video display beam progresses down the 
screen. 

This colour changing can be avoided by taking one of the following precautions: 

Use a four bitplane playfield, which only allows the lower 16 colours to be rendered into the BitMap 
(and allows Hires display mode). 



If a 32-colour playfield display is being used, avoid rendering in colours 17-19, 21-23, 25-27, and 29-32, 
which are the colours affected by the VSprite system. 

Specify the VSprite SprColors pointer as a value of NULL to avoid changing the contents of any of the 
hardware sprite colour registers. This may cause the VSprites to change colours depending on their 
positions relative to each other, as described in the previous section. 
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Using Bobs 

The following section describes how to define a Bob (blitter object). Like VSprites, a Bob is a software construct 
designed to make animation easier. The main advantage of a Bob over a VSprite is that it allows more colours 
and a width greater than 16 pixels to be defined. 

To create a Bob, you need both a Bob structure and a VSprite structure. The components common to all GELs - 
height, collision-handling information, position in the drawing area and pointers to the image definition - are part 
of the VSprite structure. The added features - such as drawing sequence, data about saving and restoring the 
background, and other features not applicable to VSprites - are further specified in the Bob structure. 

THE VSPRITE STRUCTURE AND BOBS 

The root VSprite structure is set up as described earlier for true VSprites, with the following exceptions: 
Y, X Bob position is always in pixels that are the same resolution as the display. 

Flags For Bobs, the VSPRITE flag must be cleared. SAVEBACK or OVERLAY can also be 

used. 
Height, Width Bob pixels are the size of the background pixels. The Width of Bobs may be 

greater than one word. 
Depth The Depth of a Bob may be up to as deep as the playfield, provided that enough 

image data is provided. 
ImageData This is still a pointer to the image, but the data there is organized differently. 

SprColors This pointer should be set to NULL for Bobs. 

VSBob This is a pointer to the Bob structure set up as described below. 

VSPRITE FLAGS AND BOBS 

The bits in the VSprite.Flags field that apply to a Bob are the VSPRITE flag, the SAVEBACK flag and the 
OVERLAY flag. When a VSprite structure is used to define a Bob, the VSPRITE flag in the VSprite.Flags field 
must be set to zero. This tells the system that this GEL is a Bob type. 

To have the GEL routines save the background before the Bob is drawn and restore the background after the 
Bob is removed, specify the SAVEBACK flag (stands for "save the background") in the VSprite structure Flags 
field. If this flag is set, the SaveBuffer must have been allocated, which is where the system puts this saved 
background area. The buffer must be large enough to save all the background bitplanes, regardless of how many 
planes the Bob has. The size in words can be calculated as follows: 

I* Note that Bob. Width is in units of words. */ 

size = Bob.Width* Bob.Height* RastPort.BitMap.Depth; 

To allocate this space, the graphics function AllocRaster() can be used. AllocRaster() takes the width in bits, so 
it is a convenient way to allocate the space needed. The makeBobQ routine below shows another way to 
correctly allocate this buffer. For example: 

I* space for 16 bits times 5 lines times 5 bitplanes*/ 
myBob.SaveBuffer =AllocRaster( (UWORD) 16, (UWORD) (5 * 5) ); 
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Warning: The SaveBuffer must be allocated from Chip memory and contain an even 
number of word-aligned bytes. The AllocRasterQ function does this for you. The 
AllocRaster() function rounds the width value up to the next integer multiple of 16 bits 
which is greater than or equal to the current value an it obtains memory from the Chip 
memory pool. 

OVERLAY is the other VSprite.Flags item that applies to Bobs. If this flag is set, it means that the background's 
original pixels show through in any area where there are bits in the Bob's shadow mask (ImageShadow, 
explained later). The space for the ImageShadow shadow mask must have been allocated and initialized. The 
ImageShadow mask must be allocated from Chip memory. 

If the OVERLAY bit is cleared, the system uses the entire rectangle of words that define the Bob image to replace 
the playfield area at the specified x,y coordinates. See the paragraphs below called "ImageShadow." 

THE BOB STRUCTURE 

The Bob structure is defined in the include file <graphics/gels.h> as follows: 

struct Bob 

{ 

WORD Flags; /* General purpose flags */ 

WORD *SaveBuffer; /* buffer for background buffer */ 

WORD * ImageShadow; /* shadow mask of image */ 

struct Bob *Before; /* draw this Bob before Bobs on the list*/ 

struct Bob *After; /* draw this Bob after Bobs on the list */ 

struct VSprite *BobVSprite; /* this Bob's VSprite definition */ 

struct AnimComp *BobComp; /* pointer to this Bob's AnimComp def */ 

struct DBuf Packet *DBuffer; /* pointer to this Bob's dBuf packet */ 

BUserStuff BUserExt; /* Bob user extension */ 

}; 

The Bob structure itself does not need to be in Chip memory. The (global) static declaration of a Bob structure 
could be done like so: 

struct Bob myBob = 

{ 

0, NULL, NULL, NULL, NULL, NULL, NULL, NULL, 

}; 

However, since most of the Bob structure members are pointers, it is more common to allocate and set the Bob 
up dynamically. Refer to the makeBob() and freeBob() functions in the "animtools.c" example at the end of the 
chapter for an example of allocating, initializing and freeing a Bob structure. 

Linking Bob and VSprite Structures 

The VSprite and Bob structures must point to one another, so that the system can find the entire GEL. structures 
are linked with statements like this: 

myBob. BobVSprite = &myVSprite; 
myVSprite.VSBob = kmyBob; 

Now the system (and the application program) can go back and forth between the two structures to obtain the 
various Bob variables. 
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USING BOB FLAGS 



The following paragraphs describe how to set the Flags field in the Bob structure (note that these flags do not 
apply to the Flags field of the VSprite structure). 

SAVEBOB 

To tell the system not to erase the old image of the Bob when the Bob is moved, specify the SAVEBOB 
flag in the Bob structure Flags field. This makes the Bob behave like a paintbrush. It has the opposite 
effect of SAVEBACK. 

It's Faster To Draw A New Bob. It takes longer to preserve and restore the raster image 
than simply to draw a new Bob image wherever required. 

BOBISCOMP 

If this Bob is part of an AnimComp, set the BOBISCOMP flag in the Bob structure to I. If the flag is a I, 
the pointer named BobComp must have been initialized. Otherwise, the system ignores the pointer, and 
it may be left alone (though it's good practice to initialize it to NULL). See "Animation Structures and 
Controls" for a discussion of AnimComps. 

BWAITING 

This flag is used solely by the system, and should be left alone. When a Bob is waiting to be drawn, the 
system sets the BWAITING flag in the Bob structure to 1 . This occurs only if the system has found a 
Before pointer in this Bob's structure that points to another Bob. Thus, the system flag BWAITING 
provides current draw-status to the system. Currently, the system clears this flag on return from each call 
to DrawGList(). 

BDRAWN 

This is a system status flag that indicates to the system whether or not this Bob has already been drawn. 
Therefore, in the process of examining the various Before and After flags, the drawing routines can 
determine the drawing sequence. The system clears this flag on return from each call to DrawGList(). 

BOBSAWAY 

To initiate the removal of a Bob during the next call to DrawGList(), set BOBSAWAY to 1 . Either the 
application or the system may set this Bob structure system flag. The system restores the background 
where it has last drawn the Bob. The system will unlink the Bob from the system GEL list the next time 
DrawGListQ is called, unless the application is using double-buffering. In that case, the Bob will not be 
unlinked and completely removed until two calls to DrawGListQ have occurred and the Bob has been 
removed from both buffers. The RemBob() macro sets the BOBSAWAY flag. 

BOBNIX 

When a Bob has been completely removed, the system sets the BOBNIX flag to 1 on return from 
DrawGListQ. In other words, when the background area has been fully restored and the Bob has been 
removed from the GEL list, this flag in is set to a 1 . BOBNIX is especially significant when double- 
buffering because when an application asks for a Bob to be removed, the system must remove it from 
both the drawing buffer and from the display buffer. Once BOBNIX has been set, it means the Bob has 
been removed from both buffers and the application is free to reuse or deallocate the Bob. 

SAVEPRESERVE 

The SAVEPRESERVE flag is a double-buffer version of the SAVEBACK flag. If using double-buffering and 
wishing to save and restore the background, set SAVEBACK to 1 . SAVEPRESERVE is used by the 
system to indicate whether the Bob in the "other" buffer has been restored; it is for system use only. 
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SPECIFYING THE SIZE OF A BOB 

Bobs do not have the 16-pixel width limit that applies to VSprites. To specify the overall size of a Bob, use the 
Height and Width members of the root VSprite structure. Specify the Width as the number of 16-bit words it 
takes to fully contain the object. The number of lines is still specified with the Height member in the VSprite data 
structure. 

As an example, suppose the Bob is 24 pixels wide and 20 lines tall. Use statements like the following to specify 
the size: 



myVSprite. Height = 20; /* 20 lines tall. */ 

myVSprite. Width =2; /* 24 bits fit into two words. */ 

Because Bobs are drawn into the background playfield, the pixels of the Bob are the same size as the 
background pixels, and share the colour palette of the ViewPort. 

SPECIFYING THE SHAPE OF A BOB 

The layout of the data of a Bob's image is different from that of a VSprite because of the way the system retrieves 
data to draw Bobs. VSprite images are organized in a way convenient to the Sprite hardware; Bob images are set 
up for easy blitter manipulation. The ImageData pointer is still initialized to point to the first word of the image 
definition. 

Note: As with all image data, a Bob's ImageData must be in Chip memory for access by 
the blitter. 

The sample image below shows the same image defined as a VSprite in the "Using Virtual Sprites" section 
above. The data here, however, is laid out for a Bob. The shape is 2 planes deep and is triangular: 



mem 
mem + 1 
mem + 2 
mem + 3 
mem + 4 



mem + 5 
mem + 6 
mem + 7 
mem + 8 
mem + 9 



<first bitplane data> 
1111 1111 1111 1111 
0011 1100 0011 1100 
0000 1100 0011 0000 
0000 0010 0100 0000 
0000 0001 1000 0000 

<Second bitplane data> 
1111 1111 1111 1111 
0011 0000 0000 1100 
0000 1111 1111 0000 
0000 0011 1100 0000 
0000 0001 1000 0000 



Least significant bit of sprite line 1 
Least significant bit of sprite line 2 
Least significant bit of sprite line 3 
Least significant bit of sprite line 4 
Least significant bit of sprite line 5 



Most significant bit of sprite line 1 
Most significant bit of sprite line 2 
Most significant bit of sprite line 3 
Most significant bit of sprite line 4 
Most significant bit of sprite line 5 



<more bitplanes of data if Bob is deeper> 
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SPECIFYING THE COLORS OF A BOB 

Typically a five-bitplane, low-resolution mode display allows playfield pixels (and therefore, Bob pixels) to be 
selected from any of 32 active colours out of a system palette of 4,096 different colour choices. Bob colours are 
limited to the colours used in the background playfield. 

The system ignores the SprColors member of the VSprite structure when the VSprite structure is the root of a 
Bob. Instead, the Bob's colours are determined by the combination of the Depth of the Bob image and its 
PlanePick, PlaneOnOff and ImageShadow members. 

Use the Depth member in the VSprite structure to indicate how many planes of image data is provided to define 
the Bob. This also defines how many colours the Bob will have. The combination of bits in corresponding Y,X 
positions in each bitplane determines the colour of the pixel at that position. 

For example, if a Depth of one plane is specified, then the bits of that image allow only two colours to be 
selected: one colour for each bit that is a 0, a second colour for each bit that is a I. Likewise, if there are 5 planes 
of image data, all 32 colours can be used in the Bob. The Bob Depth must not exceed the background depth. 
Specify Depth using a statement such as the following: 



myVSprite .Depth = 5; /* Allow a 32 colour, 5-bitplane image. */ 



OTHER ITEMS INFLUENCING BOB COLOURS 

The three other members in the VSprite structure that affect the colour of Bob pixels are ImageShadow, 
PlanePick, and PlaneOnOff. 

ImageShadow 

The ImageShadow member is a pointer to the shadow mask of a Bob. A shadow mask is the logical or of all 
bitplanes of a Bob image. The system uses the shadow mask in conjunction with PlaneOnOff, discussed below, 
for colour selection. It also uses the shadow mask to "cookie cut" the bits that will be overwritten by this Bob, to 
save and later restore the background. 

The following figure shows the shadow mask of the image described above. 

mem + 1111111111111111 Shadow mask for line 1 

mem + 1 0011 1100 0011 1100 Shadow mask for line 2 

mem + 2 0000 1111 1111 0000 Shadow mask for line 3 

mem + 3 0000 00111100 0000 Shadow mask for line 4 

mem + 4 0000 0001 1 000 0000 Shadow mask for line 5 

Space for the ImageShadow must be provided and this pointer initialized to point to it. The amount of memory 
needed is equivalent to one plane of the image: 

shadow_size = myBob->BobVSprite->Height * myBob->BobVSprite->Width; 

The example image is 5 high and 1 word wide, so, 5 words must be made available. 

Note: The ImageShadow memory must be allocated from Chip memory (MEMF_CHIP). 

638 Amiga ROM Kernel Reference Manual: Libraries 

PlanePick 

Because the Depth of the Bob can be less than the background, the PlanePick member is provided so that the 
application can indicate which background bitplanes are to have image data put into them. The system starts with 
the least significant plane of the Bob, and scans PlanePick starting at the least significant bit, looking for a plane 
of the RastPort to put it in. 

For example, if PlanePick has a binary value of: 1 1 (0x03) then the system draws the first plane of 
the Bob's image into background plane and the second plane into background plane 1 . 

Alternatively, a PlanePick value of: 1 1 (0x12) directs the system to put the first Bob plane into plane 
1 , and the second Bob plane into plane 4. 

PlaneOnOff 

What happens to the background planes that aren't picked? The shadow mask is used to either set or clear the 
bits in those planes in the exact shape of the Bob if OVERLAY is set, otherwise the entire rectangle containing 
the Bob is used. The PlaneOnOff member tells the system whether to put down the shadow mask as zeros or 
ones for each plane. The relationship between bit positions in PlaneOnOff and background plane numbers is 
identical to PlanePick: the least significant bit position indicates the lowest numbered bitplane. A zero bit clears 
the shadow mask shape in the corresponding plane, while a one bit sets the shadow mask shape. The planes 
Picked by PlanePick have image data - not shadow mask - blitted in. 

This provides a great deal of colour versatility. One image definition can be used for many Bobs. By having 
different PlanePick / PlaneOnOff combinations, each Bob can use a different subset of the background colour 
set. 



There is a member in the VSprite structure called CollMask (the collision mask, covered under "Detecting GEL 
Collisions") for which the application may also reserve some memory space. The ImageShadow and CollMask 
pointers usually, but not necessarily, point to the same data, which must be located in Chip memory. If they point 
to the same location, obviously, the memory only need be allocated once. 

An example of the kinds of statements that accomplish these actions (see the makeVSprite() and makeBob() 
examples for more details): 

#define BOBW 1 
#define BOBH 5 
#define BOBD 2 

/* Data definition from example layout */ 
WORD chip BobData[]= 

{ 

OxFFFF, 0x300C, OxOFFO, 0x03C0, OxOlBO, 
OxFFFF, 0x3E7C, 0x0C30, 0x03C0, 0x0180 



/* Reserve space for the collision mask for this Bob */ 
WORD chip BobCollision[BOBW * BOBH] ; 

myVSprite .Width = BOBW; /* Image is 16 pixels wide (1 word) */ 
myVSprite .Height = BOBH; /* 5 lines for each plane of the Bob */ 
myVSprite .Depth = BOBD; /* 2 Planes are in ImageData */ 

/* Show the system where it can find the data image of the Bob */ 
myVSprite . ImageData = BobData; 
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/* binary 0101, render image data into bitplanes and 2 */ 
myVSprite. PlanePick = 0x05; 

/* binary 0000, means colours 1, 9, and 5 will be used. 

* binary 0010 would mean colours 3, 6, and 7. 

* binary 1000 would mean colours 9, C, and D. 

* binary 1010 would mean colours H, E, and F. 
*/ 

myVSprite. PlaneOnOff = 0x00; 

/* Where to put collision mask */ 
myVSprite. CollMask = BobCollision; 

/* Tell the system where it can assemble a GEL shadow */ 
/* Point to same area as CollMask */ 
myBob . ImageShadow = BobCollision; 

/* Create the Sprite collision mask in the VSprite structure */ 
InitMasks (kmyVSprite) ; 

BOB PRIORITIES 

This subsection describes the choices for inter-Bob priorities. The inter-Bob priorities tell the system what order to 
render the Bobs. Bobs rendered earlier will appear to be behind later Bobs. A Bob drawn earlier is said to have 
the lower priority and a Bob drawn later is said to have the higher priority. Thus, the highest priority Bob will be 
drawn last and will never be obstructed by another Bob. 



Letting the System Decide Priorities 

The priority issue can be ignored and the system will render the Bobs as it finds them in the Gelslnfo list. To do 
this, set the Bob's Before and After pointers to NULL. Since the Gelslnfo list is sorted by GEL x, y values, Bobs 
that are higher on the display will appear behind the lower ones, and Bobs that are more to the left on the display 
will appear behind Bobs on the right. 

As Bobs are moved about the display, their priorities will change. 

Specifying the Drawing Order 

To specify the priorities of the Bobs, use the Before and After pointers. Before points to the Bob that this Bob 
should be drawn before, and After points to the Bob that this Bob should be drawn after. By following these 
pointers, from Bob to Bob, the system can determine the order in which the Bobs should be drawn. (Take care to 
avoid circular dependencies in this list!) 

Note: This terminology is often confusing, but, due to historical reasons, cannot be 
changed. The system does not draw the Bobs on the Before list first, it draws the Bobs 
on the After list first. Next, it draws the current Bob, and, finally, the Bobs on the Before 
list. 

For example, to assure that myBobl always appears in front of myBob2, The Before and After pointers must be 
initialized so that the system will always draw myBobl after myBob2. 

myHob2 .Before = &myBobl; /* draw Bob2 before drawing Bobl */ 

myBob2 . After = NULL; /* draw Bob2 after no other Bob */ 

myBobl. After = &myBob2 ; /* draw Bobl after drawing Bob2 */ 

myBobl .Before = NULL; /* draw Bobl before no other Bob */ 
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As the system goes through the Gelslnfo list, it checks the Bob's After pointer. If this is not NULL, it follows the 
After pointer until it hits a NULL. Then it starts rendering the Bobs, going back up the Before pointers until it hits 
a NULL. Then it continues through the Gelslnfo list. So, it is important that all Before and After pointers of a 
group properly point to each other. 

Note: In a screen with a number of complex GELs, you may want to specify the Before 
and After order for Bobs that are not in the same AnimOb. This will keep large objects 
together. If you do not do this, you may have an object drawn with half of its Bobs in 
front of another object! Also, in sequences you only set the Before and After pointers for 
the active AnimComp in the sequence. 

ADDING A BOB 

To add a Bob to the system GEL list, use the AddBob() routine. The Bob and VSprite structures must be correct 
and cohesive when this call is made. See the makeBob() and makeVSprite() routines in the animtools.c file 
listed at the end of this chapter for a detailed example of setting up Bobs and VSprites. See the setupGelSys() 
function for a more complete example of the initialization of the GELs system. 

For example: 

struct Gelslnfo myGelsInfo = {Ob- 
struct VSprite dummySpriteA = {o}, dummySpriteB = {Ob- 
struct Bob myBob = (Ob- 
struct RastPort rastport = (0) ; 

/* Done ONCE, for this Gelslnfo. See setupGelSys ( ) at the end of this 

** chapter for a more complete initialization of the Gel system 

*/ 



InitGels (kdummySpriteA, &dummySpriteB, &myGelsInfo) ; 

/* Initialize the Bob members here, then AddBob ( ) */ 
AddBob ( kmyBob , krastport); 

REMOVING A BOB 

Two methods may be used to remove a Bob. The first method uses the RemBob() macro. RemBob() causes the 
system to remove the Bob during the next call to DrawGList() (or two calls to DrawGList() if the system is 
double-buffered). RemBobQ asks the system to remove the Bob at the next convenient time. See the 
description of the BOBSAWAY and BOBNIX flags above. It is called as follows: 

struct Bob myBob = {0] ; 

RemBob (kmyBob) ; 

The second method uses the RemBob() routine. RemBob() tells the system to remove this Bob immediately. For 
example: 

struct BobmyBob = {Ob- 
struct RastPort rastport = {Ob- 
struct Viewport viewport = {o}; 

RemBob ( &myBob , &rastport, kviewport) ; 

This causes the system to erase the Bob from the drawing area and causes the immediate erasure of any other 
Bob that had been drawn subsequent to (and on top of) this one. The system then unlinks the Bob from The 
system GEL list. To redraw the Bobs that were drawn on top of the one just removed, another call to 
DrawGList() must be made. 
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SORTING AND DISPLAYING BOBS 

As with VSprites, the Gelslnfo list must be sorted before any Bobs can be displayed. This is accomplished with 
the SortGList() function. For Bobs, the system uses the position information to decide inter-Bob priorities, if not 
explicitly set by using the Bob. Before and Bob.After pointers. 

Once the Gelslnfo list has been sorted, the Bobs in the list can be displayed by calling DrawGList(). This call 
should then be followed by a call to WaitTOF() if the application wants to be sure that the Bobs are rendered 
before proceeding. Call these functions as follows: 

struct RastPort myRastPort = {o}; /* Of course, these have to be initialized... */ 
struct Viewport myVlewPort = {o}; 

SortGList (kmyRastPort) ; 

DrawGLlst (&myRastPort , &myViewPort) ; /* Draw the elements (Bobs only) */ 

WaitTOF ( ) ; 

Warning: If your Gelslnfo list contains VSprites in addition to Bobs, you must also call 
MrgCop() and LoadViewQ to make all the GELs visible. Or, under Intuition, 
RethinkDisplayO must be called to make all the GELs visible. 

CHANGING BOBS 

The following characteristics of Bobs can be changed dynamically between calls to DrawGListQ: 



To change the location of the Bob in the RastPort drawing area, adjust the X and Y values in the 
VSprite structure associated with this Bob. 

To change a Bob's appearance, the pointer to the ImageData in the associated VSprite structure may 
be changed. Note that a change in the ImageData also requires a change or recalculation of the 
ImageShadow, using lnitMasks(). 

To change a Bob's colours modify the PlanePick, PlaneOnOff or Depth parameters in the VSprite 
structure associated with this Bob. 

To change a Bob's display priorities, alter the Before and After pointers in the Bob structure. 

To change the Bob into a paintbrush, specify the SAVEBOB flag in the Bob.Flags field. 

Changes Are Not Immediately Seen. Neither these nor other changes are evident until 
SortGList() and then DrawGList() are called. 

COMPLETE BOB EXAMPLE 

This example must be linked with animtools.c and includes the header files animtools.h and animtools_proto.h. 
These files are listed at the end of the chapter. 

/* bob.c 
* * 

** SAS/C V5 .10a 

** lc -bl -cfist -v -y bob.c 

** blink FROM LIBrc.o bob . o animtools.o LIB LIB :1c. lib LIB : amiga . lib TO bob 

*/ 

#include <exec/types . h> 

#include <exec/memory . h> 

#include <intuition/intuitionbase . h> 

#include <graphics/gfx.h> 
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#include <graphics/gfxbase . h> 
#include <graphics/gels.h> 
tinclude <libraries/dos . h> 
#include <stdlib.h> 
#include "animtools.h" 

VOID bobDrawGList (struct RastPort *rport, struct Viewport *vport) ; 
VOID process_window( struct Window 'win, struct Bob 'myBob) ; 
VOID do Bob (struct Window *win) ; 

struct GfxBase *Gf xBase; /*' pointer to Graphics library */ 

struct IntuitionBase *IntuitionBase; /* pointer to Intuition library*/ 
int return_code; 

#define GEL SIZE 4 /* number of lines in the bob */ 

/* Bob data - two sets that are alternated between. Note that this */ 
/* data is at the resolution of the screen. */ 

/* data is 2 planes by 2 words by GEL_SIZE lines */ 
WORD chip bob_datal [2 * 2 * GEL_SIZE] = 

{ 

/* plane 1 */ 

Oxffff, 0x0003, OxfffO, 0x0003, OxfffO, 0x0003, Oxffff, 0x0003, 

/* plane 2 */ 

Ox3fff, Oxfffc, Ox3ff0, OxOffc, Ox3ff0, OxOffc, Ox3fff, Oxfffc 

}; 

/* data is 2 planes by 2 words by GEL_SIZE lines */ 



WORD chip bob data2 [2 * 2 * GEL SIZE] = 

{ 

/* plane 1 */ 

OxcOOO, Oxffff, OxcOOO, OxOfff, OxcOOO, OxOfff, OxcOOO, Oxffff, 

/* plane 2 */ 

Ox3fff, Oxfffc, Ox3ff0, OxOffc, Ox3ff0, OxOffc, Ox3fff, Oxfffc 

}; 

NEWBOB myNewBob = /* Data for the new bob structure defined in animtools.h 

*/ 

{ /* Initial image, WORD width, line 

height */ 

bob_data2, 2, GEL_SIZE, /* Image depth, plane pick, plane on off, VSprite 

flags */ 

2, 3, 0, SAVEBACK I OVERLAY, /* dbuf (0 = false), raster depth, x,y position, hit mask, 

*/ 

0, 2, 160, 100, 0,0, /* me mask */ 

}; 

atruct NewWindow myNewWindow = 

{ /* information for the new window */ 

80, 20, 900, 150, -1, -1, CLOSEWINDOW | INTUITICKS, 

ACTIVATE | WINDOWCLOSE | WINDOWDEPTH | RMBTRAP, 

NULL, NULL, "Bob", NULL, NULL, 0, 0, 0, 0, WBENCHSCREEN 

}; 

/* Draw the Bobs into the RastPort. */ 

VOID bobDrawGList (struct RastPort *rport, struct Viewport *vport) 

{ 

SortGList (rport) ; 
DrawGList (rport , vport) ; 

/' If the GelsList includes true VSprites, MrgCop ( ) and LoadViewO here */ 
WaitTOF () ; 

}; 

/* Process window and dynamically change bob: Get messages. Go away on CLOSEWINDOW. 
*' Update and redisplay bob on INTUITICKS. Wait for more messages. 

*/ 

VOID process window(struct Window *win, struct Bob *myBob) 

{ 

atruct IntuiMessage *msg; 

FOREVER 

{ 

Wait(lL << win->UserPort->mp_SigBit) ; 
while (NULL != (msg = (struct IntuiMessage *) GetMsg (win->UserPort) ) ) 

{ 

/* only CLOSEWINDOW and INTUITICKS are active */ 
if (msg->Class == CLOSEWINDOW) 

{ 

ReplyMsg ( (struct Message *)msg); 
return; 
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/* Must be INTUITICKS: change x and y values on the fly. Note: 
** do not have to add window offset, Bob is relative to the 
** window (sprite relative to screen) . 

*/ 

myBob->BobVSprite->X = msg->MouseX + 20; 
myBob->BobVSprite->Y = msg->MouseY + 1; 
ReplyMsg ( (struct Message *)msg); 

} 

/* after getting a message, chanqe image data on the fly */ 
myBob->BobVSprite->ImageData= (myBob->BobVSprite->ImaqeData==bob_datal) 
? bob_data2 : bob_datal ; 

InitMasks (myBob->BobVSprite) ; /* set up masks for new image */ 

bobDrawGList (win->RPort, ViewPortAddress (win) ) ; 



} 

/* Workinq with the Bob: setup the GEL system, and get a new Bob (makeBobO) . 
** Add the bob to the system and display. Use the Bob. When done, remove 
** the Bob and update the display without the bob. Cleanup everything. 

*/ 

VOID do_Bob (struct Window *win) 

{ 

struct Bob *myBob; 

struct Gelslnfo *my ginfo; 

if (NULL == (my_ginfo = setupGelSys (win->RPort , 0x03))) 

return_code = RETURN_WARN ; 
else 

{ 

if (NULL == (myBob = makeBob (kmyNewBob) ) ) 

returncode = RETURN_WARN; 
else 



{ 



} 



} 



} 



AddBob (myBob, win->RPort) ; 

bobDrawGList (win->RPort, ViewPortAddress (win) ) ; 

process_window (win, myBob); 

RemBob (myBob) ; 

bobDrawGList (win->RPort, ViewPortAddress (win) ) ; 

freeBob (myBob, myNewBob.nb RasDepth) ; 

cleanupGelSys (my ginfo, win->RPort) ; 



/* Example bob program: First open up the libraries and a window. */ 
VOID main(int argc, char **argv) 

{ 

struct Window *win; 

returncode = RETURN_0K; 

if (NULL == (GfxBase = (struct GfxBase * ) OpenLlbrary (GRAPHICSNAME, 37L) ) ) 

returncode = RETURN_FAIL; 
else 

{ 

if (NULL == (IntuitionBase = (struct IntuitionBase *) OpenLibrary (INTUITIONNAME, 37L) ) ) 
return_code = RETURN_FAIL; 
else 



{ 



} 



if (NULL == (win = OpenWindow ( &myNewWindow) ) ) 

returncode = RETUAN_FAIL; 
else 

{ 

do Bob (win) ; 
CloseWindow (win) ; 

} 

CloseLibrary ( (struct Library *) IntuitionBase) ; : 



CloseLibrary ( (struct Library *) GfxBase); 

} 

exit (return code) ; 
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DOUBLE-BUFFERING 

Double-buffering is the technique of supplying two different memory areas in which the drawing routines may 
create images. The system displays one memory space while drawing into the other area. This eliminates the 
"flickering" that is visible when a single display is being rendered into at the same time that it is being displayed. 



Double-buffering For One Means Double-buffering For All. If any of the Bobs is double- 
buffered, then all of them must be double-buffered. 

To find whether a Bob is to be double-buffered, the system examines the pointer named DBuffer in the Bob 
structure. If this pointer has a value of NULL, the system does not use double-buffering for this Bob. For example: 

myBob. DBuffer =NULL; /* do this if this Bob is NOT double-buffered*/ 

DBuf Packet and Double-Buffering 

For double-buffering, a place must be provided for the system to store the extra information it needs. The system 
maintains these data, and does not expect the application to change them. The DBufPacket structure consists of 
the following members: 

BufY, BufX Lets the system keep track of where the object was located n the last frame" (as compared to the 
Bob structure members called oldY and oldX that tell where the object was two frames ago). BufY 
and BufX provide for correct restoration of the background within the currently active drawing 
buffer. 

BufPath Assures that the system restores the backgrounds in the correct sequence; it relates to the 
VSprite members DrawPath and ClearPath. 

BufBuffer This field must be set to point to a buffer the same size as the Bob's SaveBuffer. This buffer is 
used to store the background for later restoration when the system moves the object. This buffer 
must be allocated from Chip memory. 

To create a double-buffered Bob, execute a code sequence similar to the following: 

struct Bob myBob = { } ; 

struct DBufPacket myDBuf Packet = {o}; 

/" Allocate a DBufPacket for myBob same size as previous example */ 
if (NULL != (myDBuf Packet .BufBuffer = AllocRaster (48 , 20 * 5))) 

{ 

/* tell Bob about its double buff status */ 
myBob. DBuf f er = myDBuf Packet ; 
} 

The example routines makeBob() and freeBobQ in the animtools.c listing at the end of this chapter show how to 
correctly allocate and free a double-buffered Bob. 
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Collisions and GEL Structure Extensions 



This section covers two topics that are applicable to all GELs: how to extend GEL data structures for your own 
purposes and how to detect collisions between GELs and other graphics objects. 

DETECTING GEL COLLISIONS 

All GELs, including VSprites, can participate in the software collision detection features of the graphics library. 
Simple Sprites must use hardware collision detection. See the Amiga Hardware Reference Manual for 
information about hardware collision detection. 

Two kinds of collisions are handled by the system routines: GEL-to-boundary hits and GEL-to-GEL hits. You can 
set up as many as 16 different routines to handle different collision combinations; one routine to handle the 
boundary hits, and up to fifteen more to handle different inter-GEL hits. 

You supply the actual collision handling routines, and provide their addresses to the system so that it can call 
them as needed (when the hits are detected). These addresses are kept in a collision handler table pointed to by 



the CollHandler field of the Gelslnfo list. Which routine is called depends on the 16-bit MeMask and HitMask 
members of the VSprite structures involved in the collision. 

When you call DoCollision(), the system goes through the Gelslnfo list which, is constantly kept sorted by x, y 
position. If a GEL intersects the display boundaries and the GELs HitMask indicates it is appropriate, the 
boundary collision routine is called. When DoCollisionQ finds that two GELs overlap, it compares the MeMask of 
one with the HitMask of the other. If corresponding bits are set in both, it calls the appropriate inter-GEL collision 
routine at the table position corresponding to the bits in the HitMask and MeMask, as outlined below. 

Preparing for Collision Detection 

Before you can use the system to detect collisions between GELS, you must allocate and initialize a table of 
collision-detection routines and place the address of the table in the Gelslnfo. CollHandler field. This table is an 
array of pointers to the actual routines that you have provided for your collision types. You must also prepare 
some members of the VSprite structure: CollMask, BorderLine, HitMask, and MeMask. 

Building a Table of Collision Routines 

The collision handler table is a structure, CollTable, defined in <graphics/gels.h>. It is accessed as the 
ConHandler member of the Gelslnfo structure. The table only needs to be as large as the number of bits for 
which you wish to provide collision processing. It is safest, though, to allocate space for all 16 entries, considering 
the small amount of space required. 

Call the routine SetCollision() to initialize the table entries that correspond to the HitMask and MeMask bits that 
you plan to use. Do not set any of the table entries directly, instead give the address to SetCollision() routine 
and let it handle the set up of the Gelslnfo. CollTable field. 
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For example, SetCollision() could be called as follows: 

ULONG num; 

VOID (*routine) () ; 

struct Gelslnfo *GInfo; 

VOID myCollisionRoutine (GELA, GELB) /* sample collision routine */ 
struct VSprite *GELA; 
struct VSprite *GELB; 

{ 

/* process GELs here - GELA and GELB point to the base VSprites of */ 
/* the GELs, you can use the user extensions to identify what hit */ 
/* (if you need the info) . */ 

/* Gelslnfo must be allocated and initialized */ 

routine = myCollisionRoutine; 

SetCollision (num, routine, Glnfo) 
} 

The num argument is the collision table vector number (0-15). The (*routine)() argument is a pointer to your 
collision routine. And the Clnfo argument is a pointer to the Gelslnfo structure. 

VSprite Collision Mask 

The CollMask member of the VSprite is a pointer to a memory area allocated for holding the collision mask of 
that GEL. This area must be in Chip memory and its size is the equivalent of one bitplane of the GEL's image. 
The collision mask is usually the same as the shadow mask of the GEL, formed from a logical-OR combination of 
all planes of the image. The following figure shows an example collision mask. 



If this is the image in plane 1, 



.and this is the image in plane 2. 
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Figure 23-3; A Collision Mask 

Alternatively, you may have a collision mask that is not derived from the image. In this case, the actual image 
isn't relevant. The system will not register collisions unless the other objects touch the collision mask. If the 
collision mask is smaller than the image, other objects will pass through the edges without a collision. 
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VSprite BorderLine 

For faster collision detection, the system uses the BorderLine member of the VSprite structure. BorderLine 
specifies the location of the horizontal logical-OR combination of all of the bits of the object. It may be compared 
to taking the whole object's shadow/collision mask and squishing it down into a single horizontal line. You provide 
the system with a place to store this line. The size of the data area you allocate must be at least as large as the 
image width. 

In other words, if it takes three 16-bit words to hold one line of a GEL, then you must reserve three words for the 
BorderLine. In the VSprite examples, the routine makeVSprite() correctly allocates and initializes the collision 
mask and borderline. For example: 

WORD myBorderLineData [3 j ; /* reserve space for BorderLine for this Bob */ 
myVSprite .BorderLine = myBorderLineData; /* tell the system where it is */ 

Here is a sample of an object and its BorderLine image: 

011000001100 Object 

001100011000 

001100011000 

000110110000 

000010100000 



011110111100 



BorderLine image 



Using this squished image, the system can quickly determine if the image is touching the left or rightmost 
boundary of the drawing area. 

To establish default BorderLine and CollMask data, call the lnitMasks() function. 



VSprite HitMask and MeMask 

Software collision detection is independently enabled and disabled for each GEL. Further, you can specify which 
of 16 possible collision routines you wish to have automatically executed. DoCollision(), in addition to sensing an 
overlap between objects, uses these masks to determine which routine (if any) the system will call when a 
collision occurs. 

When the system determines a collision, it performs a logical-AND of the HitMask of the upper-leftmost object in 
the colliding pair with the MeMask of the lower-rightmost object of the pair. The bits that are 1s after the 
logical-AND operation choose which one of the 16 possible collision routines to perform. 

If the collision is with the boundary, bit is always a 1 and the system calls the collision handling 
routine number 0. Always assign the routine that handles boundary collisions to vector in the 
collision handling table. The system uses the flag called BORDERHIT to indicate that an object has 
landed on or moved beyond the outermost bounds of the drawing area (the edge of the clipping 
region). The VSprite example earlier in this chapter uses collision detection to check for border hits. 

If any one of the other bits (1 to 15) is set, then the system calls your collision handling routine 
corresponding to the bit set. 

If more than one bit is set in both masks, the system calls the vector corresponding to the rightmost 
(the least significant) bit only. 
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Using HitMask and MeMask 

This section illustrates the use of the HitMask and MeMask to define one type of collision. 

Suppose there are two classes of objects that you wish to control on the display: ENEMYTANK and MYMISSILE. 
Objects of class ENEMYTANK should be able to pass across one another without registering any collisions. 
Objects of class MYMISSILE should also be able to pass across one another without collisions. However, when 
MYMISSILE and ENEMYTANK collide, the system should generate a call to a collision routine. 

Choose a pair of collision detect bits not yet assigned within MeMask, one to represent ENEMYTANK, the other 
to represent MYMISSILE. You will use the same two bits in the corresponding HitMask. In this example, bit 1 
represents ENEMYTANK objects and bit 2 represents MYMISSLE objects. 





MeMask 


HitMask 


Bit Number 


21 


21 


ENEMYTANK1 


1 


1 


ENEMYTANK2 


01 


1 


MYMISSILE 


1 


01 



In the MeMask, bit 1 is set to indicate that this object is an ENEMYTANK. Bit 2 is clear (zero) indicating this 
object is not a MYMISSILE object. In the HitMask for ENEMYTANK objects, bit 1 is clear (zero) which means, "I 
will not register collisions with other ENEMYTANK objects." However, bit 2 is set (one) which means, "I will 
register collisions with MYMISSILE objects." 

Thus when a call to DoCollision() occurs, for any objects that appear to be colliding, the system ANDs the 
MeMask of one object with the HitMask of the other object. If there are non-zero bits present, the system will call 
one of your collision routines. 

In this example, suppose that the system senses a collision between ENEMYTANK 1 and ENEMYTANK 2. 
Suppose also that ENEMYTANK 1 is the top/leftmost object of the pair. Here is the way that the collision testing 
routine performs the test to see if the system will call any collision-handling routines: 



Bit Number 2 1 

ENEMYTANK I MeMask 1 

ENEMYTANK 2 HitMask 1 

Result of logical-AND 

Therefore, the system does not call a collision routine. But suppose that DoCollision() finds an overlap between 
ENEMYTANK 1 and MYMISSILE, where MYMISSILE is the top/leftmost of the pair: 

Bit Number 2 1 

MYMISSILE MeMask 1 

ENEMYTANK 2 HitMask 1 

Result of logical-AND 1 

Therefore, the system calls the collision routine at position 2 in the table of collision-handling routines. 
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SETTING UP FOR BOUNDARY COLLISIONS 

To specify the region in the playfield that the system will use to define the outermost limits of the GEL 
boundaries, you use these Gelslnfo members: topmost, bottommost, leftmost, and rightmost. The 
DoCollision() routine tests these boundaries when determining boundary collisions within this RastPort. They 
have nothing whatsoever to do with graphical clipping. Graphical clipping makes use of the RastPort's clipping 
rectangle. 

Here is a typical program segment that assigns the members correctly (for boundaries 50,100, 80, 240). It 
assumes that you already have a RastPort structure pointer named myRastPort. 

myRastPort->GelsInf o->topmost = 5 0; 

myRastPort ->GelsInfo->bottommost = 100; 

myRastPort ->GelsInf o->lef tmost = 80; 

myRastPort->GelsInf o->rightmost = 240; 

Parameters To Your Boundary Collision Routine 

During the operation of the DoCollisionQ routine, if you have enabled boundary collisions for a GEL (by setting 
the least significant bit of its HitMask) and it has crossed a boundary, the system calls the boundary routine you 
have defined. The system will call the routine once for every GEL that has hit, or gone outside of the boundary. 
The system will call your routine with the following two arguments: 

A pointer to the VSprite structure of the GEL that hit the boundary 

A flag word containing one to four bits set, representing top, bottom, left and right boundaries, telling 
you which of the boundaries it has hit or exceeded. To test these bits, compare to the constants 
TOPHIT, BOTTOMHIT, LEFTHIT, and RIGHTHIT. 

See the VSprite example given earlier for an example of using boundary collision. 

Parameters To Your Inter-GEL Collision Routines 

If, instead of a GEL-to-boundary collision, DoCollision() senses a GEL-to-GEL collision, the system calls your 
collision routine with the following two arguments: 

Address of the VSprite that is the uppermost (or leftmost if y coordinates are identical) GEL of a 
colliding pair. 



Address of the VSprite that is the lowermost (or rightmost if y coordinates are identical) GEL of the 
pair. 

Handling Multiple Collisions 

When multiple elements collide within the same display field, the following set of sequential calls to the collision 
routines occurs: 

The system issues each call in a sorted order for GELs starling at the upper left-hand corner of the 
screen and proceeding to the right and down the screen. 

For any colliding GEL pair, the system issues only one call, to the collision routine for the object that is 
the topmost and leftmost of the pair. 
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ADDING USER EXTENSIONS TO GEL DATA STRUCTURES 

This section describes how to expand the size and scope of the VSprite, Bob and AnimOb data structures. In 
the definition for these structures, there is an item called UserExt at the end of each. If you want to expand these 
structures (to hold your own special data), you define the UserExt member before the <graphics/gels.h> file is 
included. If this member has already been defined when the <graphicslgels.h> file is parsed, the compiler 
preprocessor will extend the structure definition automatically. If these members have not been defined, the 
system will make them SHORTs, and you may still consider these as being reserved for your private use. 

To show the kind of use you can make of this feature, the example below adds speed and acceleration figures to 
each GEL by extending the VSprite structure. When your collision routine is called, it could use these values to 
transfer energy between the two colliding objects (say, billiard balls). You would have to set up additional 
routines, executed between calls to DoCollision(), that would add the values to the GELs position appropriately. 
You could do this with code similar to the following: 

struct mylnfo 

{ 

short xvelocity; 

short yvelocity; 

short xaccel; 

short yaccel; 
} 

These members are for example only. You may use any definition for your user extensions. You would then also 
provide the following line, to extend the VSprites structure, use: 

/* Redefine VUserStuff for my own use. */ 
#define VUserStuff struct mylnfo 

To extend the Bobs structure, use: 

#define BUserStuff struct mylnfo 
To extend the AnimObs structure, use: 

#define AUserStuff struct mylnfo 

When the system is compiling the <graphics/gels.h> file with your program, the compiler preprocessor 
substitutes "struct mylnfo" everywhere that UserExt is used in the header. The structure is thereby customized to 
include the items you wish to associate with it. 

Typedef Cannot Be Used. You cannot use the C-language construct typedef for the 
above statements. If you want to substitute your own data type for one of the UserStuff 



variables, you must use a #define. 
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Animation with GELs 

An animation sequence is composed of a series of drawings. Each drawing differs from the preceding one so that 
when they are arranged in a stack and viewed sequentially, the images appear to flow naturally. 

In classic film animation, image drawing is done in two stages. The background for each scene is painted just 
once. Then, the cartoon characters and any other foreground objects are painted on transparent sheets of 
celluloid called cells which are placed over the background. With cells, animation can be achieved by redrawing 
only the parts of the scene that move while the background stays the same. Animation on the Amiga works 
similarly. The background is formed by the playfield while the objects that move can be conveniently handled with 
the GELs system. 

ANIMATION DATA STRUCTURES 

There are two main data structures involved in Amiga animation: AnimComp and AnimOb. 

The AnimComp (Animation Component), is an extension of the Bob structure discussed in the previous section. 
An AnimComp provides a convenient way to link together a series of images so that they can be sequenced 
automatically, and so multiple sequences can be grouped together. An AnimComp is analogous to one sheet of 
celluloid representing a single image to be placed over the background. 

struct AnimComp 

{ 

WORD Flags; /* AnimComp flags for system & user */ 

WORD Timer; 

WORD TimeSet; 

struct AnimComp *NextComp; 

struct AnimComp *PrevComp; 

struct AnimComp *NextSeq; 

struct AnimComp *PrevSeq; 

WORD (*AnimCRoutine) () ; 

WORD YTrans; 

WORD XTrans; 

struct AnimOb *HeadOb; /* Pointer back to the controlling AnimOb */ 

struct Bob *AnimBob; /* Underlying Bob structure for this AnimComp */ 

}; 

The AnimComp structure contains pointers, PrevSeq and NextSeq, that lets you group these cells into stacks 
that will be viewed sequentially. The AnimComp structure also has PrevComp and NextComp pointers that let 
you group stacks into complex objects containing multiple independently moving parts. 

The second animation data structure is the AnimOb which provides the variables needed for overall control over 
a group of AnimComps. The AnimOb itself contains no imagery; it simply provides a common reference point 
for the sequenced images and specifies how the system should move that point. 

struct AnimOb 

{ 

struct AnimOb *NextOb, *PrevOb; 
LONG Clock; 

WORD AnOldY, AnOldX; /* old y,x coordinates */ 

WORD AnY, AnX; /* y,x coordinates of the AnimOb*/ 

WORD YVel, XVel; /* velocities of this object */ 

WORD YAccel, XAccel; /* acceleration of this object */ 

WORD RingYTrans, RingXTrans; /* ring translation values */ 

WORD (*AnimORoutine) () ; /* address of user procedure */ 

struct AnimComp *HeadComp; /* pointer to first component */ 



AUserStuff AUserExt; 



/* AnimOb user extension 
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These structures can be used in various ways. A simple animation of a rotating ball could be created with three or 
four AnimComps linked together in a circular fist by their NextSeq and PrevSeq fields. The system displays the 
initial AnimComp (the "top of the stack"), then switches to the AnimComp pointed to by NextSeq, and then 
switches to its NextSeq and so on until it reaches the end of the sequence. The sequence starts over again 
automatically if the last AnimComp.NextSeq points back to the first AnimComp in the stack. 

For a more complex animation of a walking human, you could use five stacks, i.e., five circular lists of 
AnimComps; four stacks for the arms and legs and a single stack for the head and torso. To group these tacks 
into one cohesive unit showing a human figure, you use the PrevComp and NextComp pointers in the 
AnimComp structure. All the stacks would also share a common AnimOb, so that the combined sequences can 
be moved as a single object. 




AnimComp AnimComp AnimComp AnimComp AnimComp 



^ 



K 



AnimOb 



Figure 28-4: Linking AnimComps For a Multiple Component AnimOb 



ANIMATION TYPES 



The GELs system provides several ways of setting up automatic animation, loosely based on some categories 
of movement in real life. Some things (like balls or arrows) can move independently of the background, and look 
even more realistic if they tumble or rotate as they move; other things (like worms, wheels, and people) must be 
anchored to the background, or they will appear to slide unnaturally. 



The system software allows these types of animation through simple motion control, motion control with 
sequenced drawing, and sequenced drawing using Ring Motion Control. 
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Simple Motion Control 



To produce motion of a simple object, such as a ball, the object is simply moved relative to a background display, 
a little at a time. This is simple motion control, and can be accomplished with one AnimComp and one AnimOb, 
by simply changing the AnimOb's position every N video frames. The apparent speed of the object is a 
combination of how often it is moved (every frame, every other frame, etc.) and how far it is moved (how much 
the AnimOb's AnX and AnY are changed). 

Sequenced Drawing 

To make the ball appear to rotate is a little more complex. To produce apparent movement within the image, 
sequencing is used. This is done by having a stack of AnimComp's that are laid down one after the other, a 
frame at a time. The stack can be arranged in a circular list for repeating movement. So, when you combine a 
sequence of drawings using AnimComps with simple motion control using an AnimOb, you can perform more 
complex animations such as having a rotating ball bounce around. 

Ring Motion Control 

Making a worm appear to crawl is similar to the rotating ball. There is still a stack of AnimComps that are 
sequenced automatically, and one controlling AnimOb. But each AnimComp image is drawn so that it appears to 
move relative to an internal point that remains stationary throughout the stack. So instead of the AnimOb's 
common reference point moving in each frame, you tell the system how far to move only at the end of each 
AnimComp sequence. 



AnlmQb common 
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Figure 28-5: Ring Motion Control 
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As illustrated in the figure at left, the sequence of events for Ring Motion Control look like this: 

Draw AnimCompI , Draw AnimComp2, Draw AnimComp3, Move AnimOb, 
Draw AnimCompI , Draw AnimComp2, Draw AnimComp3, Move AnimOb, 
Draw AnimCompI... 

SPECIFYING ANIMATION COMPONENTS 

For each AnimComp, you initially specify: 

A pointer to the AnimComp's controlling AnimOb. 

Initial and alternate views, their timing and order. 

The initial inter-component drawing priorities (for multiple AnimComp sequences, this specifies which 
sequence to display frontmost). 

A pointer to a special animation routine related to this component (optional). 

Your own extensions to this structure (optional). 

Sequencing AnimComps 

To specify the sequencing of AnimComp images, the pointers called PrevSeq and NextSeq are used to build a 
doubly-linked list. The sequence can be made circular (and usually is) by linking the first and last AnimComps in 
the sequence: the NextSeq of the last AnimComp must point back to the first AnimComp, and the PrevSeq of 
the first AnimComp must point to the last AnimComp. If the list is a loop, then the system will continue to cycle 
through the list until it is stopped. If the list is not a loop, then the program must act to restart the sequence after 
the last item is displayed. The AnimCRoutine field of the last AnimComp can be used to do this. 

Position of an AnimComp 

To specify the placement of each AnimComp relative to its controlling AnimOb, you set the AnimComp 
members XTrans and YTrans. These values can be positive or negative. 

The system is designed so that only one of the AnimComps in any given sequence is "active" (being displayed) 
at a given point in time. It is the only image in the sequence that is (or is about to be) linked into the Gelslnfo list. 
The Timer determines how long each Component in the sequence remains active, as described below. 

Specifying Time for Each Image 

The AnimComp members Timer and TimeSet are used to specify how long the system should keep each 
sequential image on the screen. 

When the system makes an animation component active, it copies the value you have put in the TimeSet 
member into the Timer member. As the animation proceeds, the system decrements Timer; as long as it is 
greater than zero, then that AnimComp remains active. When the Timer value reaches zero, the system makes 
the next AnimComp in the sequence active, and the process repeats. 
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If you initialize the value in TimeSet to zero, the system will not sequence this component at all (and Timer will 
remain zero). 

Linking Multiple AnimComp Sequences 



When an AnimOb is built from multiple AnimComp sequences, the sequences are linked together by the 
PrevComp and NextComp fields of the AnimComps. These pointers must be initialized only in the initial 
AnimComp of each sequence. The other components that are not initially active should have their PrevComp 
and NextComp pointers set to NULL. 

Do Not Use Empty Fields. You cannot store data in the empty PrevComp and 
NextComp fields. As the system cycles through the AnimComps, the NextComp and 
PrevComp fields are set to NULL when an old AnimComps is replaced by a new 
AnimComp. The new AnimComp is then linked in to the list of sequences in place of the 
old one. 

Component Ordering 

The PrevSeq, NextSeq, PrevComp and NextComp linkages have no bearing on the order in which 
AnimComps in any given video frame are drawn. To specify the inter-component priorities (so that the closest 
objects appear frontmost) the Before and After pointers in the initially active AnimComp's underlying Bob 
structure are linked in to the rest of the system, as described previously in the discussion of Bobs. 

This setup needs to be done once, for the initially active AnimComps of the AnimOb only. 

The animation system adjusts the Before and After pointers of all the underlying Bob structures to constantly 
maintain the inter-component drawing sequence, even though different components are being made active as 
sequencing occurs. 

These pointers also assure that one complete object always has priority over another object. The Bob Before and 
After pointers are used to link together the last AnimComp's Bob of one AnimOb to the first AnimComp's Bob of 
the next AnimOb. 



SPECIFYING THE ANIMATION OBJECT 

For each AnimOb, you initially specify: 

The starting position of this object 

Its velocity and acceleration (optional). 

A pointer to the first of its AnimComps. 

A pointer to a special animation routine related to this object (optional). 

Your own extensions to this structure (optional). 
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Linking the AnimComp Sequences to the AnimOb 

Within each AnimOb there may be one or more AnimComp sequences. The HeadComp of the AnimOb points 
to the first AnimComp in the list of sequences. 

Each sequence is identified by its "active" AnimComp. There can only be one active AnimComp in each 
sequence. The sequences are linked together by their active AnimComps; for each of these the NextComp and 
PrevComp fields link the sequences together to create a list. The first sequence in the list (HeadComp of the 
AnimOb), has its PrevComp set to NULL. The last sequence in the list has its NextComp set to NULL. None of 
the inactive AnimComps should have NextComp or PrevComp fields set. 

To find the active AnimComp at run time, you can look in the AnimOb's HeadComp field. To find the active 
AnimComp from any another AnimComp, use the HeadOb field to find the controlling AnimOb first and then 
look in its HeadComp field to find the active AnimComp. 

The figure below shows all the linkages in data structures needed to create the animation GELs. 
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Figure 26-6: Linking ol an AnimOb 
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To position the object and its component parts, use the AnimOb structure members AnX and AnY. The following 
figure illustrates how each component has its own offset from the AnimOb's common reference point. 
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Figure 28-7: Specifying an AnimOb Position 



When you change the animation object's AnX and AnY, all of the component parts will be redrawn relative to it 
the next time DrawGList() is called. 

Setting Up Simple Motion Control 

In this form of animation, you can specify objects that have independently controllable velocities and 
accelerations in the X and Y directions. Components can still sequence. 

The variables that control this motion are located in the AnimOb structure and are called: 

YVel, XVel-the velocities in the y and x directions. These values are added to the position values on 
each call to Animate() (see below). 

YAccel, XAccel-the accelerations in the x and y directions. These values are added to the velocity 
values on each call to Animate() (see below). The velocity values are updated before the position 
values. 
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Setting Up Ring Motion Control 

To make a given component trigger a move of the AnimOb you set the RINGTRIGGER bit of that AnimComp's 
Flags field. When the system software encounters this flag, it adds the values of RingXTrans and RingYTrans 
to the AnX and AnY values of the controlling AnimOb. The next time you execute DrawGI_ist(), the drawing 
sequence will use the new position. 



You usually set RINGTRIGGER in only one of the animation components in a sequence (the last one); however, 
you can use this flag and the translation variables any way you wish. 

Using Sequenced Drawing and Motion Control 

If you are using Ring Motion Control, you will probably set the velocity and acceleration variables to zero. For 
instance, consider the example of a person walking. With Ring Motion Control, as each foot falls it is positioned 
on the ground exactly where originally drawn. If you included a velocity value, the person's foot would not be 
stationary with respect to the ground, and the person would appear to "skate" rather than walk. If you set the 
velocity and acceleration variables at zero, you avoid this problem. 

When the system activates a new AnimComp, it checks the Flags field to see if the RINGTRIGGER bit is set. If 
so, the system adds RingYTrans and RingXTrans to AnY and AnX respectively. 

THE ANIMKEY 

The system uses one pointer, known as the AnimKey, to keep track of all the AnimObs via their PrevOb and 
NextOb linkage fields. The AnimKey acts as the anchor for the list of AnimObs you are using and is initialized 
with code such as the following: 

struct AnimOb *animKey; 

lnitAnimate(&animKey); I* Only do this once to initialize the AnimOb list*/ 

As each new object is added (via AddAnimOb()), it is linked in at the beginning of the list, so AnimKey will 
always point to the object most recently added to the list. To search forward through the list, start with the 
AnimKey and move forward on the NextOb link. Continue to move forward until the NextOb is NULL, indicating 
the end of the list. The PrevOb link will allow you to move back to a previous object. 

Set Up PrevOb and NextOb Correctly. It is important that the NextOb link of the last 
object is NULL, and that the PrevOb of the first object is NULL. In fact, the system 
expects the animation object lists to be exactly the way that they are described above. If 
they are not, the system will produce unexpected results. 

ADDING ANIMATION OBJECTS 

Use the routine AddAnimOb() to add animation objects to the controlled object list. This routine will link the 
PrevOb and NextOb pointers to chain all the AnimObs that the system is controlling. 

struct RastPort myRPort ; 

struct AnimOb myAnimOb; 

struct AnimOb *animKey; /* Must be initialized with InitAnimate ( ) */ 

AddAnimOb (&myAnimOb, sanimKey, kmyRPort) ; 
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MOVING THE OBJECTS 

When you have defined all of the structures and have established all of the links, you can call the Animate() 
routine to move the objects. Animate() adjusts the positions of the objects as described above, and calls the 
various subroutines (AnimCRoutines and AnimORoutines) that you have specified. 

After the system has completed the Animate() routine, some GELs may have been moved, so the Gelslnfo list 
order may possibly be incorrect. Therefore, the list must be re-sorted with SortGListQ before passing it to a 
system routine. 



If you are using collision detection, you then perform DoCollision(). Your collision routines may also have an 
effect on the relative position of the GELs. Therefore, you should again call SortGList() to assure that the system 
correctly orders the objects before you call DrawGList(). When you call DrawGList(), the system renders all the 
GELs it finds in the Gelslnfo list and any changes caused by the previous call to Animate() can then be seen. 

This is illustrated in the following typical call sequence: 

struct AnimOb **myAnimKey; 
struct RastPort *rp; 
struct Viewport *vp; 

/* ... setup of graphics elements and objects */ 

Animate (myAnimKey, rp) ; /* "move" objects per instructions */ 

SortGList (rp) ; /* put them in order */ 

DoCollision (rp) ; /* software collision detect/action */ 

SortGList (rp) ; /* put them back into right order */ 

DrawGList (vp, rp) ; /* draw into current RastPort */ 

YOUR OWN ANIMATION ROUTINE CALLS 

The AnimOb and AnimComp structures can include pointers for your own routines that you want the system to 
call. These pointers are stored in the AnimOb's AnimORoutine field and in the AnimComp's AnimCRoutine 
field, respectively. 

When Animate() is called, the system performs the following steps for every AnimOb in the AnimKey list: 

Updates the AnimOb's location and velocities. 

Calls the AnimOb.AnimORoutine routine if one is supplied. 

The for each AnimComp of the AnimOb: 

- If this sequence times out, switches to the new AnimComp. 

- Calls the AnimComp. AnimCRoutine if one is supplied. 

- Sets the underlying VSprite's x,y coordinates. 

If you want a routine to be called, you put the address of the routine in either AnimComp. AnimCRoutine or 
AnimOb.AnimORoutine member as needed. If no routine is to be called, you must set these fields to NULL. 
Your routines will be passed one parameter, a pointer to the AnimOb or AnimComp it was related to. You can 
use the user structure extensions discussed earlier to hold the variables you need for your own routines. 
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For example, if you provide a routine such as this: 

VOID MyOCode (struct AnimOb *anOb) 

{ 

/* whatever needs to be done */ 

} 

Then, if you put the address of the routine in an AnimOb structure: 

myAnimOb .AnimORoutine = MyOCode; 

MyOCodeQ will be called with the address of this AnimOb when AnimateQ processes this AnimOb. 



STANDARD GEL RULES STILL APPLY 



Before you use the animation system, you must have called the routine lnitGels(). The section called "Bob 
Priorities" describes how the system maintains the list of GELs to draw on the screen according to their various 
data fields. The animation system selectively adds GELs to and removes GELs from this list of screen objects 
during the Animate() routine. On the next call to DrawGList(), the system will draw the GELs in the list into the 
selected RastPort. 



ANIMATIONS SPECIAL NUMBERING SYSTEM 

Velocities and accelerations can be either positive or negative. The system treats the velocity, acceleration and 
Ring values as fixed-point binary fractions, with the decimal point at position 6 in the word. That is: 
vvvvvvvvvv.ffffff where v stands for actual values that you add to the x or y (AnX, AnY) positions of the object for 
each call to Animate(), and f stands for the fractional part. By using a fractional part, you can specify the speed 
of an object in increments as precise as 1/64th of an interval. 

If you set the value of XVel at 0x0001 , it will take 64 calls to the Animate() routine before the system will modify 
the object's x coordinate position by a step of one. The system constant ANFRACSIZE can be used to shift 
values correctly. So if you set the value to (1 « ANFRACSIZE), it will be set to 0x0040, the value required to 
move the object one step per call to Animate(). The system constant ANIMHALF can be used if you want the 
object to move every other call to Animate(). 

Each call you make to AnimateQ simply adds the value of XAccel to the current value of XVel, and YAccel to 
the current value of YVel, modifying these values accordingly. 

ANIMTOOLS.H AND ANIMTOOLS.C 

Hem is the listing of the animtools.h header file and the animtools.c link file used by the examples in this chapter. 
The makeSeq() and makeComp() subroutines here demonstrates how to use the GELs animation system. 

/* animtools.h */ 
#ifndef GELTOOLS_H 
#define GELTOOLS_H 

/* 

** These data structures are used by the functions in animtools.c to 

** allow for an easier interface to the animation system. 

*/ 

/* Data sCrucCure to hold informaLion for a new VSprite. */ 
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typedef struct newVSprite 
{ 



WORD 


*nvs Image; 




/* 


image data for the vsprite 


*/ 


WORD 


*nvs_Colourset ; 


/* 


colour array for the vsprite 


*/ 


SHORT 


nvs WordWidth; 


/* 


width in wozds 


*/ 


SHORT 


nvs LineHed 


-giit ; 


/* 


heiqht in lines 




SHORT 


nvs_ImageDepth ; 


/* 


depth of the image 


*/ 


SHORT 


nvs X ; 






/* initial x position 




SHORT 


nvs Y ; 






/* initial y position 




SHORT 


nvs Flags ; 




/* 


vsprite flags 


*/ 


USHORT 


nvs HitMask; 


/* Hit 


mas 


k. */ 




USHORT 


nvs MeMask; 


/* Me 


mask 


*/ 




JEWVSPRITE; 












Data structure to hold information for a new Bob. */ 





/ 

typedef struct newBob 

{ 

WORD *nb_Image; /* image data for the bob */ 
SHORT nb_WordWidth; /* width in words */ 
SHORT nb_LineHeight ; /* height in lines */ 



SHORT nb_ImageDepth; 
SHORT nb_PlanePick; 
SHORT nb_PlaneOnOff ; 
SHORT nb_BFlags ; 
SHORT nb_DBuf ; 
SHORT nb_RasDepth; 
SHORT nb_X ; 
SHORT nb_Y ; 

USHORT nb_HitMask; /* 

USHORT nb_MeMask; /* 

NEWBOB ; 



/* depth of the image */ 

/* planes that get image data */ 

/* unused planes to turn on */ 

/* bob flags */ 

/* l=double buf, 0=not */ 

/* depth of the raster */ 



/* 
/* 



initial x position 
initial y position 



Hit mask. 
Me mask. 



/* Data structure to hold information for a new animation component, 
typedef struct newAnimComp 



WORD 


(*nac Routine) () ; 


SHORT 


nac Xt ; 


SHORT 


nac Yt; 


SHORT 


nac Time; 


SHORT 


nac CFlags ; 



/* routine called when Comp is displayed. 

/* initial delta offset position. 

/* initial delta offset position. 

/* Initial Timer value. 

/* Flags for the Component. 



} NEWANIMCOMP; 



/* Data structure to hold information for a new animation sequence, 
typedef struct newAnimSeq 



struct 


Ani 


mOb 


*nas HeadOb; 




WORD 






*nas_Images; 


/ 


SHORT 






*nas_Xt; 


/ 


SHORT 






*nas Yt; 


/ 


SHORT 






*nas Times; 


/ 


WORD 






(**nas Routines) () ; 




SHORT 






nas_CFlags; 


/ 


SHORT 






nas_Count ; 


/ 


SHORT 






nas Singlelmage; 


/ 


} NEWANIMSEQ; 









/* common Head of Object. 
array of Comp image data 
arrays of initial offsets, 
arrays of initial offsets, 
array of Initial Timer value. 

/* Array of fns called when comp drawn 
Flags for the Component . 
Num Comps in seq (= arrays size) 
one (or count) images. 



#define INTUITIONNAME " intuition . library" /* intuitionbase -h does not define a library name. 
*/ 



#include "animtools _proto,h" 
#endif 



/* Include prototyping */ 



/* animtools_proto . h */ 
#include <clib/dos_protos . h> 
#include <clib/exec_protos . h> 
#include <clib/graphics_protos . h> 
#include <clib/intuition protos.h> 

struct Gelslnfo *setupGelSys (struct RastPort *rPort, BYTE reserved) 

VOID cleanupGelSys (struct Gelslnfo *gInfo, struct RastPort *rPort) ; 

struct VSprite *makeVSprite (NEWVSPRITE *nVSprite) ; 

struct Bob *makeBob (NEWBOB *nBob) ; 

struct AnimComp *makeComp (NEWBOB *nBob, NEWANIMCOMP *nAnimComp) ; 

struct AnimComp *makeSeq (NEWBOB *nBob, NEWANIMSEQ *nAnimSeq) ; 

VOID freeVSprite (struct VSprite *vsprite) ; 

VOID freeBob (struct Bob *bob, LONG rasdepth) ; 

VOID freeComp (struct AnimComp *myComp, LONG rasdepth); 

VOID free5eq (struct AnimComp *headComp, LONG rasdepth}; 

VOID freeOb (struct AnimOb *headOb, LONG rasdepth); 
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/* animtools. c 



* * 



This file is a collection of tools which are used with the VSprite, Bob and Animation 
system software. It is intended as a useful EXAMPLE, and while it shows what must be 
done, it is not the only way to do it. If Not Enough Memory, or error return, each 
cleans up after itself before returning. NOTE that these routines assume a very specific 
structure Co the GEL lists. Make sure that you use the correct pairs together 
(i.e. makeObO /freeObO , etc.) 



** Compile with SAS/C S . 10b : lc -bl -cfist -v -y -oanimtools . o animtools.c 
*/ 

#include <exec/types . h> 
#include <exec/memory . h> 
#include <graphics/gfx.h> 
#include <graphics/gels . h> 
#include <graphics/clip .h> 
#include <graphics/rastport . h> 
#include <graphics/view.h> 
#include <qraphics/gfxbase . h> 
#include "animtools . h" 

/* Setup the GELs system. After this call is made you can use VSprites, Bobs, AnimComps 

** and AnimObs . Note that this links the Gelslnfo structure into the RastPort, and calls 

** InitGelsO . It uses information in your RastPort structure to establish boundary collision 

** defaults at the outer edges of the raster. This routine sets up for everything - collision 

** detection and all. You must already have run LoadView before ReadyGelSys is called. 

*/ 

struct Gelslnfo *setupGelSys (struct RastPort *rPort, BYTE reserved) 

{ 

struct Gelslnfo *gInfo; 
struct VSprite 'vsHead 
struct VSprite 'vsTail 

if (NULL != (glnfo = (struct Gelslnfo *)AllocMem (sizeof (struct Gelslnfo), MEMF CLEAR))) 

{ 

if (NULL != (glnfo- >nextLine = (WORD *) AllocMem (sizeof (WORD) * 8, MEMF CLEAR))) 

{ 

if (NULL != (gInfo->lastColour = (WORD **) AllocMem (sizeof (LONG) * 8, MEMF CLEAR))) 

{ 

if (NULL != (gInfo->collHandler = (struct collTable *) 
AllocMem (sizeof (struct collTable) , MEMF CLEAR))) 



{ 

MEMF CLEAR) ) ) 



} 



if (NULL != (vsHead = (struct VSprite *) A 

AllocMem( (LONG) sizeof (struct VSprite), MEMF CLEAR))) 

if (NULL != (vsTail = (struct VSprite *) AllocMem (sizeof (struct VSprite) 



glnfo- >sprRsrvd = reserved; 

/* Set left- and top-most to 1 to better keep items */ 

/* inside the display boundaries. */ 

glnfo- >leftmost = glnfo- >topmost = 1; 

glnfo- >rightmost = (rPort->BitMap->BytesPerRow << 3) - 1; 

glnfo- >bottommost = rPort->BitMap->Rows - 1; 

rPort->GelsInf o = glnfo ; 

InitGels (vsHead, vsTail, glnfo); 

return (glnfo) ; 



FreeMem (vsHead, (LONG) sizeof (*vsHead) ) ; 

} 

FreeMem (glnfo- >collHandler, (LONG) sizeof (struct collTable)); 

} 

FreeMem (glnf o->lastColour , (LONG) sizeof (LONG) * 8); 

} 

FreeMem (glnfo- >nextLine, (LONG) sizeof (WORD) * 8); 

} 

FreeMem (glnfo, (LONG) sizeof (*gInfo) ) ; 

return (NULL) ; 
} 

/* Free all of the stuff allocated by setupGelSys ( ) . Only call this routine if 

** setupGelSys ( ) returned successfully. The Gelslnfo structure is the one returned 

** by eetupGelSys ( ) . It also unlinks the Gelslnfo from the RastPort. 

*/ 
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VOID cleanupGelSys (struct Gelslnfo *gInfo, struct RastPort *rPort) 

{ 

rPort->GelsInfo = NULL; 

FreeMem (glnf o->collHandler, (LONG) sizeof (struct collTable) ) ; 
FreeMem(gInfo->lastColour, (LONG) sizeof (LONG) * 8); 
FreeMem (glnf o->nextLine, (LONG) sizeof (WORD) * 8); 
FreeMem (glnf o->gelHead, (LONG) sizeof (struct VSprite)); 
FreeMem(gInfo->gelTail, (LONG) sizeof (struct VSprite)); 
FreeMem (glnf o, (LONG) sizeof (*qInfo) ) ; 
} 

/* Create a VSprite from the information given in nVSprite. Use f reeVSprite ( ) 
** to free this GEL. 

*/ 

struct VSprite *makeVSprite (NEWVSPRITE *nVSprite) 

{ 

struct VSprite *vsprite; 
LONG line_size; 

LONG plane_size; 

line_size = sizeof (WORD) * nVSprite->nvs_WordWidth; 
plane_size = line size * nVSprite->nvs LineHeight; 

if (NULL != (vsprite = (struct VSprite *) AllocMem ( (LONG) sizeof ( struct VSprite), MEMF 
CLEAR) ) ) 

{ 

if (NULL != (vsprite- >BorderLine = (WORD *) AllocMem ( line size, MEMF CHIP))) 



{ 



} 



if (NULL != (vsprite->CollMask = (WORD *) AllocMem (plane size, MEMF CHIP))) 

{ 

vsprite- >Y = nVSprite ->nvs_Y; 
vsprite- >X = nVSprite- >nvs_X; 
vsprite- >Flags = nVSprite- >nvs_Flags, • 
vsprite- >Width = nVSprite- >nvs_WordWidth; 
vsprite- >Depth = nVSprite- >nvs_ImageDepth; 
vsprite- >Height = nVSprite- >nvs_LineHeight; 
vsprite- >MeMask = nVSprite- >nvs_MeMask; 
vsprite- >HitMask = nVSprite- >nvs_HitMask; 
vsprite- >ImageData = nVSprite ->nvs_Image; 
vsprite- >SprColours = nVSprite ->nvs_Colourset ; 
vsprite->PlanePick = vsprite- >PlaneOnOff = 0x00; 
InitMasks (vsprite) ; 
return (vsprite) ; 

} 

FreeMem (vsprite- >BorderLine, line size); 

FreeMem (vsprite, (LONG) sizeof (*vsprite) ) ; 



} 

return (NULL) ; 

} 

/* Create a Bob from the information given in nBob . Use freeBobO to free this GEL. 
** A VSprite is created for this bob. This routine properly allocates all double 
** buffered information if it is required. 

*/ 

struct Bob *makeBob (NEWBOB *nBob) 

{ 

struct Bob *bob; 
struct VSprite *vsprite; 
NEWVSPRITE nVSprite ; 
LONG rassize; 

rassize = (LONG) sizeof (UWORD) * nBob->nb WordWidth * nBob->nb LineHeight * nBob->nb 
RasDepth; 

if (NULL != (bob = (struct Bob *) AllocMem ( (LONG) sizeof (struct Bob), MEMF_CLEAR) ) ) 

{ 

if (NULL != (bob->SaveBuffer = (WORD *) AllocMem (rassize , MEMF_CHIP) ) ) 

{ 

nVSprite .nvs__WordWidth = nBob->nb_WordWidth; 
nVSprite .nvs_LineHeight = nBob->nb_LineHeight ; 



MEMF CHIP) ) ) 



nVSprite .nvs_ImageDepth = nBob->nb_ImageDepth; 
nVSprite .nvs_Image = nBob->nb_Image; 
nVSprite . nvs_X= nBob- >nb_X ; 
nVSprite .nvs_Y= nBob->nb_Y; 
nVSprite. nvs Colourset = NULL; 
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nVSprite .nvs_Flags = nBob->nb_BFlags ; 

/• Push the values into the NEWVSpRITE structure for use in makeVSprite ( ) . */ 

nVSprite. nvs_MeMask = nBob->nb_MeMask; 

nVSprite. nvs HitMask = nBob->nb HitMask; 

if ( (vsprite = makeVSprite (&nVSprite) ) != NULL) 

vsprite->PlanePick = nBob->nb_PlanePick; 
vsprite->PlaneOnOf f = nBob->nb_PlaneOnOf f ; 
vsprite->VSBob = bob; 
bob->BobVSprite = vsprite; 
bob->ImageShadow = vsprite->CollMask; 
bob->Flags= 0; 
bob->Before = NULL; 
bob->After = NULL; 
bob->BobComp = NULL; 

if (nBob->nb DBuf) 

{ 

if (NULL != (bob->DBuffer = (struct DBuf Packet *) 

AllocMem ( (LONG) sizeof (struct DBuf Packet) , MEMF_CLEAR) ) ) 

{ 

if (NULL != (bob- >DBuf f er- >Buf Buffer = (WORD *) AllocMem (rassize, 

return (bob) ; 
FreeMem(bob->DBuf fer, (LONG) sizeof (struct DBufPackeC) ) ; 



else 



bob->DBuffer = NULL; 
return (bob) ; 



} 



freeVSprite (vsprite) ; 

} 

FreeMem (bob->SaveBuf f er, rassize) 

FreeMem)bob, (LONG) sizeof (*bob) ) ; 



} 

return (NULL) ; 

} 

/* 

** Create a Animation Component from the information given in nAnimComp and nBob. Use 

** freeCompt) to free this GEL. makeCompt) calls makeBob ( ) , and links the Bob into an 

AnimComp . 

*/ 

struct AnimComp •makeComp (NEWBOB *nBob, NEWANIMCOMP *nAnimComp) 

{ 

struct Bob •compBob; 
struct AnimComp »aComp; 

if ( (aComp = AllocMem ( (LONG) sizeof (struct AnimComp) ,MEMF_CLEAR) ) != NULL) 

{ 

if ( (compBob = makeBob (nBob) ) != NULL) 

{ 

compBob- >After = compBob- >Bef ore = NULL; 

compBob- >BobComp = aComp; /* Link 'em up. */ 

aComp->AnimBob = compBob; 

aComp->TimeSet = nAnimComp- >nac_Time; /• Num ticks active. */ 

aComp->YTrans = nAnimComp- >nac_Yt ; /• Offset rel to HeadOb •/ 

aComp->XTrans = nAnimComp- >nac_Xt ; 



aComp->AnimCRoutine = nAnimComp- >nac_Routine; 

aComp->Flags= nAnimComp->nac CFlags; 

aComp->Timer= 0; 

aComp->NextSeq = aComp->PrevSeq = NULL; 

aComp->NextComp = aComp->PrevComp = NULL; 

aComp->HeadOb = NULL; 

return (aComp) ; 

} 

FreeMem(aComp, (LONG) sizeof (struct AnimComp) ) ; 

} 

return (NULL) ; 
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/" Create an Animation Sequence from the information qiven in nAnimSeq and nBob . Use 

** freeSeqO to free this GEL. This routine creates a linked list of animation components 

** which make up the animation sequence. It links them all up, making a circular list of 

** the PrevSeq and NextSeq pointers. That is to say, the first component of the sequences' 
*'*PrevSeq points to the last component; the last component of ' the sequences' NextSeq 

** points back to the first component. If dbuf is on, the underlying Bobs will be set up 

** for double buffering. If singlelmage is non-zero, the plmages pointer is assumed to 

** point to an array of only one image, instead of an array of 'count' images, and all 

** Bobs will use the same image. 
*/ 

struct AnimComp 'makeSeq (NEWBOB *nBob, NEWANIMSEQ *nAnimSeq) 

{ 

int seq; 

struct AnimComp *f irstCompInSeq = NULL; 

struct AnimComp *seqComp = NULL; 

struct AnimComp ' lastCompMade = NULL; 

LONG image_size; 

NEWANIMCOMP nAnimComp; 

/* get the initial image, this is the only imaqe that is used 
** if nAnimSeq->nas Singlelmage is non-zero. 

*/ 

nBob->nb_Image = nAnimSeq- >nas_Images ; 

image size = nBob->nb LineHeight * nBob->nb_ImageDepth * nBob->nb WordWidth; 

/* for each comp in the sequence */ 

for (seq = 0; seq < nAnimSeq- >nas Count; seq++) 

{ 

nAnimComp . nac_Xt = * (nAnimSeq- >nas_Xt + seq) ; 
nAnimComp . nac_Yt = * (nAnimSeq- >na5_Yt + seq); 
nAnimComp . nac_Time = * (nAnimSeq- >nas_Times + seq); 
nAnimComp . nac Routine = nAnimSeq- >nas_Routines [seq) ; 
nAnimComp . nac CFlags = nAnimSeq- >nas_CFlags; 
if ( (seqComp = makeComp (nBob, knAnimComp) ) == NULL) 

{ 

if (f irstCompInSeq != NULL) freeSeq (f irstCompInSeq, (LONG) nBob- >nb_RasDepth) ; 
return (NULL) ; 

} 

seqComp->HeadOb = nAnimSeq- >nas_HeadOb; 
/* Make a note of where the first component is.'/ 
if (f irstCompInSeq == NULL) f irstCompInSeq = seqComp; 
/* link the component into the list */ 

if (lastCompMade ;= NULL) lastCompMade- >NextSeq = seqComp; 
seqComp- >NextSeq = NULL; 
seqComp- >PrevSeq = lastCompMade; 
lastCompMade = seqComp ; 

/* If nAnimSeq- >nas_SingleImage is zero, the image array has nAnimSeq- >nas Count 
images . */ 

if (! nAnimSeq- >nas_SingleImage) 
nBob->nb_Image += image size; 

} 

/* On The last component in the sequence, set Next/Prev to make */ 
/" the linked list a loop of components. */ 
lastCompMade->NextSeq = f irstCompInSeq; 
f irstCompInSeq- >PrevSeq = lastCompMade; 



return (firstCompInSeq) ; 
} 

/* Free the data created by makeVSprite ( ) . Assumes images deallocated elsewhere.*/ 
VOID freeVSprite (struct VSprite *vsprite) 

{ 

LONG line_size; 
LONG plane_size; 

line_size = (LONG) sizeof (WORD) * vsprite->Width; 
plane_size = line_size * vsprite->Height ; 
FreeMem (vsprite->BorderLine, line_size) ; 
FreeMem (vsprite->CollMask, plane_size) ; 
FreeMem (vsprite, (LONG) sizeof (*vsprite) ) ; 
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/* Free the data created by makeBob ( ) . It's important that rasdepth match the depth you */ 
/* passed to makeHob ( ) when this GEL was made. Assumes images deallocated elsewhere. */ 
VOID freeBob (struct Bob *bob, LONG rasdepth) 

{ 

LONG rassize = sizeof (UWORD) * bob->BobVSprite->Width * bob->BobVSprite->Height * rasdepth; 

if (bob->DBuffer != NULL) 

{ 

FreeMem (bob- >DBuf f er->BufHuf f er , rassize) ; 

FreeMem (bob- >DBuf fer, (LONG) sizeof (struct DBufPacket) ) ; 

} 

FreeMem (bob- >SaveBuf fer , rassize) ; 
freeVSprite (bob->HobVSprite) ; 
FreeMem (bob, (LONG) sizeof (*bob) ) ; 
} 

/* Free the data created by makeComp ( ) . It's important that rasdepth match the depth you */ 
/* passed to makeComp ( ) when this GEL was made. Assumes images deallocated elsewhere. */ 
VOID freeComp (struct AnimComp *myComp, LONG rasdepth) 

{ 

freeBob (myComp->AnimBob, rasdepth) ; 

FreeMem (myComp, (LONG) sizeof (struct AnimComp)); 
} 

/* Free the data created by makeSeqO . Complimentary to makeSeqO , this routine goes through 
** the NextSeq pointers and frees the Components. This routine only goes forward through the 
** list, and so it must be passed the first component in the sequence, or the sequence must 
** be circular (which is guaranteed if you use makeSeqO) . It's important that rasdepth match 
** Che depth you passed to makeSeqO when this GEL was made. Assumes images deallocated 
elsewhere ! 

*/ 

VOID freeSeq (struct AnimComp *headComp, LONG rasdepth) 

{ 

struct AnimComp *curComp; 
struct AnimComp *nextComp; 

/* Break the NextSeq loop, so we qet a NULL at the end of the list. */ 
headComp->PrevSeq->NextSeq = NULL; 

curComp = headComp; /* get the start of the list */ 
while (curComp != NULL) 

{ 

nextComp = curComp- >NextSeq; 

freeComp (curComp, rasdepth); 

curComp = nextComp ; 
} 
} 

/* Free an animation object (list of sequences) . freeObO goes through the NextComp 

** pointers, starting at the AnimObs' HeadComp, and frees every sequence. It only 

** goes forward. It then frees the Object itself. Assumes images deallocated elsewhere! 

*/ 



VOID freeOb (struct AnimOb *headOb, LONG rasdepth) 

{ 

struct AnimComp * curSeq; 
struct AnimComp *nextSeq; 

curSeq = headOb->HeadComp; /* get the start of the list */ 
while (curSeq != NULL) 

{ 

nextSeq = curSeq- >NextComp; 
freeSeq (curSeq, rasdepth); 
curSeq = nextSeq; 

} 

FreeMem (headob, sizeof (struct AnimOb)); 
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Function Reference 



The following are brief descriptions of the Amiga's graphics animation functions. See the Amiga ROM Kernel 
Reference Manual: Includes and Autodocs for details on each function call. 



Animation Function 

AddAnimObO 

AddBob() 

AddVSprite() 

Animate() 

ChangeSprite() 

DoCollision() 

DrawGList() 

FreeGBuffers() 

FreeSprite() 

GetGBuffers() 

GetSprite() 

lnitGels() 

lnitGMasks() 

lnitMasks() 

MoveSprite() 

RemBobO 

RemlBobO 

RemVSpriteO 

SetCollision() 

SortGList() 



Table 2&1: Graphics Animation Functions 

Description 

Add an AnimOb to the linked list of AnimObs. 

Add a Bob to the current GEL list. 

Add a VSprite to the current GEL list. 

Process every AnimOb in the current animation list. 

Change the sprite image pointer. 

Test every GEL in a GEL list for collisions. 

Process the GEL list, queueing VSprites, drawing Bobs. 

Deallocate memory obtained by GetGBuffers(). 

Return sprite for use by others and virtual sprite machine. 

Attempt to allocate all buffers of an entire AnimOb. 

Attempt to get a sprite for the simple sprite manager. 

Initialize a GEL list; must be called before using GELs. 

Initialize all of the masks of an AnimOb. 

Initialize the BorderLine and CollMask masks of a VSprite. 

Move sprite to a point relative to top of ViewPort. 

Remove a Bob from the GEL list. 

Immediately remove a Bob from the GEL list and the RastPort. 

Remove a VSprite from the current GEL list. 

Set a pointer to a user collision routine. 

Sort the current GEL list, ordering its x,y coordinates. 
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Chapter 29 

Graphics Library and Text 

On the Amiga, rendering text is similar to rendering lines and shapes. The Amiga graphics library provides text 
functions based around the RastPort structure, which makes it easy to intermix graphics and text. 

About Amiga Fonts 

In order to render text, the Amiga needs to have a graphical representation for each symbol or text character. 
These individual images are known as glyphs. The Amiga gets each glyph from a font in the system font list. At 
present, the fonts in the system list contain a bitmap of a specific point size for all the characters and symbols of 
the font. 

Fonts are broken up into different font families. For example, the Amiga's Topaz is a font family. Each font family 
shares a basic look but can have a variety of styles and point sizes. 

The style of a font refers to a minor alteration in the way the plain version of the font's characters are rendered. 
Currently, the Amiga supports three font styles: bold, italics and underline (the font's style may also be 
considered plain when it does not have any of these styles). Although these styles can be inherent to a font, they 
are normally added algorithmically as text is rendered. 

On the Amiga, the point size of a font normally refers to the height of the font in pixels. For example, Topaz-8 is 8 
pixels high. Because the size of Amiga pixels varies between display modes, the appearance of a font will also 
vary between display modes. Future versions of the Amiga OS may measure font size in other units. For 
example, the standard point in the PostScript page description language normally refers to a point as being a 
square dot that is 1/72 of an inch on a side. Using a standard measuring unit such as the PostScript point makes 
it possible to create a WYSIWYG (What You See Is What You Get) display that exactly matches printer or other 
device output. 

When the Amiga first starts up, the only fonts in the system font list are Topaz-8 and Topaz-9, both of which are in 
ROM. Any other fonts must be loaded from disk or generated somehow. In Amiga operating systems prior to 
Release 2, additional fonts have to be loaded from disk (usually from the FONTS: directory) using the 
diskfont. library. For each font size of each font family there is a corresponding bitmap file on disk. If there is no 
bitmap on disk or in ROM for a specific font size, that font size is not available (if the operating system is 1 .3 or 
earlier). 
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System Fonts In Release 2 

Under Release 2 and later versions of the OS, the system has additional font sources at its disposal. If an 
application asks the diskfont. library to load a font of a size that has no corresponding bitmap on disk, the library 
can generate that size font. If diskfont. library can find a smaller or larger version of the font requested, it can 
scale that font's bitmap to the size needed. Of course, because the library is scaling a bitmap, the quality of the 
bitmap can degenerate in the scaling process. 

A more significant improvement to the diskfont. library is that contains AGFA'S Intellifont® engine. As of Release 
2.04 (V37) the diskfont. library can utilize AGFA Compugraphic font outlines. The Compugraphic fonts (CG fonts) 
are mathematical outlines that describe what the font's characters look like. The advantage of the outline fonts is 
that they can be scaled to any point size without the loss of resolution inherent in bitmap scaling. From the 
programmers point of view, no extra information is necessary for using the CG fonts, the diskfont. library takes 
care of all the scaling. Future releases of the OS may bring finer control over the font scaling engine which will 
allow an application to rotate and shear glyphs. 

The Text Function 

Amiga text rendering is centered around the graphics. library function TextQ, which renders text into a rastport: 



void Text ( struct RastPort *myrp, STRPTR mystring, ULONG count ); 

where myrp is a pointer to the target rastport, mystring is the string to render, and count is the number of 
characters of mystring to render. Text() renders at the current rastport position and it takes care of moving the 
rastport's current X position as it renders each letter. Text() only renders text horizontally, so repositioning the 
rastport's Y position (for example, for a new line) is the responsibility of the application. This is covered in more 
detail later in this chapter. 

Like the other rastport based graphics primitives, most of the text rendering attributes are specified within the 
RastPort structure itself. The current position, the color of the text, and even the font itself are all specified in the 
RastPort structure. 

Choosing the Font 

The graphics. library function SetFont() changes the rastport's current font: 

void SetFont ( struct RastPort *myrp, struct TextFont *mytf ) ; 

The parameter mytf is a pointer to an open, valid TextFont structure. The system uses the TextFont structure to 
keep track of fonts (The TextFont structure is discussed in detail later in this chapter). The OpenFont() (from 
graphics. library) and OpenDiskFont() (from diskfont.library) functions both return a pointer to a valid TextFont 
structure. The OpenFont() function will only open fonts that have already been loaded and are currently in the 
system list. Normally applications use the OpenDiskFont() call instead of OpenFont() because OpenDiskFont() 
can load and open fonts from disk as well as open those that are already in the system list. 
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Here are prototypes for these functions: 

struct TextFont *OpenDiskFont ( struct TextAttr *mytextAttr ) ; 
struct TextFont *OpenFont ( struct TextAttr *mytextAttr ) ; 

The mytextAttr argument points to a TextAttr structure that describes the requested font. The TextAttr 
structure (from <graphics/text.h>) looks like this: 



struct TextAttr { 

STRPTR ta_Name; 
UWORD ta_YSize; 
UBYTE ta_Style; 
UBYTE ta_Flags; 



/* name of the font */ 

/* height of the font */ 

/* intrinsic font style */ 

/* font preferences and flags */ 



where ta_Name is a string naming the font to open, ta_YSize is the point size of the font (normally in pixels), 
ta_Style is a bitfield describing the font style, and ta_Flags is a bitfield that further describes characteristics of 
the font. Note that the name of the font can either be the font name alone (<font name>.font) or it can be 
prepended with a full path. Without a path to the font, if the font is not already loaded into the system list, 
OpenDiskFont() will look in the FONTS: directory for the font file. If there is a path, OpenDiskFont() will look in 
that directory for the font files, allowing the user to put fonts in any directory (although this is discouraged). 
OpenFont() and OpenDiskFont() try to find a font that matches your TextAttr description. An important thing to 
remember about OpenDiskFont() is that only a process can call it (as opposed to a task). This is primarily 
because the function has to use dos. library to scan disks for font files. 

The font styles for ta_Style (from <graphics/text.h>) are: 



FSFJJNDERLINED 
FSF_BOLD 
FSF_ITALIC 
FSF EXTENDED 



The font is underlined 
The font is bolded 
The font is italicized 
The font is extra wide 



The flags for ta_Flags (from <graphics/text.h>) are: 



FPF_ROMFONT This font is built into the ROM (currently, only Topaz -8 and Topaz -9 are ROM 

fonts) . 
FPF_DISKFONT This font was loaded from disk (with diskfont.library) 



FPF_REVPATH This font is designed to be printed from from right to left (Hebrew is written 

from right to left) 
FPF_TALLDOT This font was designed for a Hires screen (640x200 NTSC, non-interlaced) 
FPF_WIDEDOT This font was designed for a Lores Interlaced screen (320x400 NTSC) 
FPF_PR0P0RTI0NAL The character widths of this font are not constant 

FPF_DESIGNED This font size was explicitly designed at this size rather than constructed. 
If you do not set this bit in your TextAttr, then the system may generate a 
font for you by scaling an existing ROM or disk font (under V36 and above) . 

For example to open an 1 1 point bold, italic Topaz font, the code would look something like this: 

/* pseudotext.c */ 

void main (void, void) 

{ 

struct TextAttr myta = { 
"topaz . font" 
11, 

FSF_ITALIC | FSF_BOLD, 
NULL 

}; 

struct TextFont *myfont, *oldfont; 
struct RastPort *myrp; 
struct Window *mywin; 

/* open the graphics and diskfont libraries and whatever else you may need */ 

if (myfont = OpenDiskFont (&myta) ) 

{ 

/* you would probably set the font of the rastport you are going to use */ 
myrp = mywin->RPort 
oldfont = myrp->Font; 
SetFont (myrp, myfont); 



/* perform whatever drawing you need to do */ 



/* time to clean up. If the rastport is not exclusively yours, 

you may need to restore the original font or other Rasport values */ 
SetFont (myrp, oldfont); 
CloseFont (myfont) ; 



} 



/* close whatever libraries and other resources you allocated */ 



The example above uses the graphics. library's SetFont() function to change the rastport's current font. Notice 
that this example restores the rastport's original font (myrp->Font) before exiting. This isn't normally necessary 
unless some other process assumes the rastport's font (or other drawing attributes) will not change. Intuition 
does not rely on the window's RPort.Font field for rendering or closing the default window font, so applications 
can change that font without having to restore it. 

Prior to Release 2, some applications assumed that any window they opened would always use Topaz-8 without 
bothering to explicitly set it. Since Topaz-8 was the normal default font before Release 2, this was usually not a 
problem. However, under Release 2 and later versions of the OS, the user can easily change the default system 
fonts with the Font Preferences editor. Hence, applications that make assumptions about the size of the default 
font look terrible under Release 2 (and in some cases are unusable). Program designers should not make 
assumptions about the system font, and wherever possible, honor the user font preferences. See the 
"Preferences" chapter of this manual for more information on how to find user preferences. 

Setting the Text Drawing Attributes 

In addition to SetFontQ, there are three rastport control functions that set attributes for text rendering: 



r p- 


ULONG 


pen ) ; 


rp, 


ULONG 


pen ) ; 


r P- 


ULONG 


drawMode 



void SetAPen ( struct RastPort 
void SetBPen ( struct RastPort 
void SetDrMd ( struct RastPort 

The color of the text depends upon the rastport's current drawing mode and pen colors. You set the draw mode 
with the SetDrMd() function passing it a pointer to a rastport and a drawing mode: JAM1 , JAM2, COMPLEMENT 
orlNVERSEID. 

If the drawing mode is JAM1 , the text will be rendered in the RastPort. FgPen color. Wherever there is a set bit in 
the character's bitmap image, Text() will set the corresponding bit in the rastport to the FgPen color. This is 
known as overstrike mode. You set the FgPen color with the SetAPen() function by passing it a pointer to the 
rastport and a color number. 
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If the drawing mode is set to JAM2, Text() will place the FgPen color as in the JAM1 mode, but it will also set the 
bits in the rastport to the RastPort. Bg Pen color wherever there is a corresponding cleared bit in the character's 
bitmap image. Basically, this prints the character themselves in the FgPen color and fills in the surrounding parts 
of the character image with the BgPen color. You set the BgPen color with the SetBPen() function by passing it 
a pointer to the rastport and a color number. 

If the drawing mode is COMPLEMENT, for every bit set in the character's bitmap image, the corresponding bits in 
the rastport (in all of the rastport's bitplanes) will have their state reversed, cleared bits in the character's bitmap 
image have no effect on the destination rastport. As with the other drawing modes, the write mask can be used to 
protect certain bitplanes from being modified (see the "graphics primitives" chapter for more details). 

The JAM1 , JAM2, and COMPLEMENT drawing modes are mutually exclusive of each other but each can be 
modified by the INVERSVID drawing mode. If you combine any of the drawing modes with INVERSVID, the 
Amiga will reverse the state of all the bits in the source drawing area before writing anything into the rastport. 

The idea of using a RastPort structure to hold all the rendering attributes is convenient if the rastport's drawing 
attributes aren't going to change much. This is not the case where several processes need to render into a 
rastport using very different drawing attributes. An easy way around this problem is to clone the RastPort. By 
making an exact duplicate of a RastPort, you can change the various rendering parameters of your RastPort 
without effecting other programs that render into the RastPort you cloned. Because a RastPort only contains a 
pointer to the rendering area (the bitmap), the original RastPort and the cloned RastPort both render into the 
bitmap, but they can use different drawing parameters (font, drawing mode, colors, etc.). 

Rendering The Text 

When the Text() routine renders text, it renders at the current rastport position along the text's baseline. The 
baseline is an imaginary line on top of which the text is rendered. Each font has a baseline that is a constant 
number of pixels from the top of the font's bitmap. For most fonts, parts of some characters are rendered both 
above and below the baseline (for example, y, g, and j usually have parts above and below the baseline). The 
part below the baseline is called the descender. 




Figure 29-1 : Descenders and Baseline of Amiga Fonts 
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Because Text() only increments the rastport's current X position as it renders text horizontally, programs that 



need 

to print several lines of text have to take care of moving the current pointer to the beginning of the next line, 

usually with the graphics. library's Move() function: 

void Move ( struct RastPort *rp, LONG x, long y ) ; 

When moving the current position to the beginning of the next line, an application must make sure it leaves 
enough space above and below the baseline to prevent characters on different lines from overlapping each other. 
There are a few fields in the TextFont structure returned by OpenFontQ and OpenDiskFont() that are useful for 
spacing and rendering text: 



struct TextFont { 

struct Message tf_Message; 



UWORD 
UBYTE 
UBYTE 
UWORD 
UWORD 
UWORD 



tf_YSize; 

tf_Style; 

tf_Flags; 

tf_XSize; 

tf_Baseline; 

tf BoldSmear; 



/* reply message for font removal */ 
/* font name in LN | used in this */ 
/* font height | order to best */ 

/* font style | match a font */ 

/* preferences and flags / request. */ 
nominal font width */ 

distance from the top of char to baseline */ 
smear to affect a bold enhancement */ 



UWORD tf_Accessors; /* access count */ 



UBYTE tf_LoChar; 
UBYTE tf_HiChar; 
APTR tf CharData; 



/* the first character described here */ 
/* the last character described here */ 
/* the bit character data */ 



UWORD tf_Modulo; 

APTR tf_CharLoc; 

APTR t f_Char Space; 

APTR tf CharKern; 



/* the row modulo for the strike font data */ 

/* ptr to location data for the strike font */ 
/* 2 words: bit offset then size */ 

/* ptr to words of proportional spacing data */ 

/* ptr to words of kerning data */ 



The fields of interest to applications are as follows. 
tf YSize 



tf XSize 



The "height", in pixels, of this font. None of the characters in this font will be taller than this value. 



This is the character width for monospaced (non-proportional) fonts. The width includes the extra space 
needed to the left and right of the character to keep the characters from running together. 



tf_Basellne 

The distance in pixels from the top line of the font to the baseline. 



tf LoChar 



This is the first character glyph (the graphical symbol associated with this font) defined in this font. All 
characters that have ASCII values below this value do not have an associated glyph. 



tf_HiChar 

This is the last character glyph defined in this font. All characters that have ASCII values above this 
value do not have an associated glyph. An application can use these values to avoid rendering 
characters which have no associated glyphs. Any characters without an associated glyph will have the 
default glyph associated to them. Normally, the default glyph is a rectangle. 
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To erase text, the graphics. library provides two functions that were specifically designed to clear parts of a 
rastport based on the dimensions of the current font: 



void ClearEOL ( struct RastPort *rp ); 
void ClearScreen( struct RastPort *rp 



Using the current font, ClearEOL() will clear the rest of the current text line from the rastport's current position to 
the edge of the rastport. ClearEOL() was introduced in the Release 2 graphics. library. ClearScreen() will clear 
the rest of the line as ClearEOLQ does, but it will also clear the rastport below the current line of text. 

Setting the Font Style 

The OpenFontQ and OpenDiskFont() functions both search through the fonts available to them, looking for the 
font that most closely matches the TextAttr structure. If these functions can't find a font that matches exactly, 
they will open the one with the same name that most closely matches the TextAttr structure's ta_YSize, 
ta_Style, and ta_Flags fields (in that order of preference). 

If the font doesn't match your style choice exactly, it is possible to ask the system to alter how it renders the font 
so it matches the style you need. The rastport contains some flags that tell the system's text rendering functions 
to algorithmically add styles to characters as they are rendered. Currently, the system can add up to three styles 
to a font: italics, bold, and underline. The system cannot alter the style of a font if the style is already intrinsic to 
the font. For example, it is not possible to add (or remove) the bold styling to a font if the font was designed to be 
bolded. There are two graphics. library functions that deal with software font style setting: 

ULONG AskSof tStyle ( struct RastPort *rp ) ; 

ULONG SetSof tStyle ( struct RastPort *rp, ULONG newstyle, ULONG enable ) ; 

The AskSoftStyle() function returns a bitmask of the style bits available to the rastport's current font. The style 
bits are the same ones used by the TextAttr's ta_Style field (from <graphics/text.h>). SetSoftStyleQ changes 
the rastport's current software style setting according to the style bits set in the newstyle field (from the function 
prototype above). 

SetSoftStyle() pays attention only to the bits of newstyle that have the corresponding bit in the enable field set 
as well. This function returns the style, which is the combined result of previous soft style selection, the effect of 
this function, and the style inherent in the set font. The following code fragment turns on the algorithmic font 
attributes for the rastport (myrastport) based on those style attributes that were requested in the 
OpenDiskFont() call (mytextattr.ta_Style) and not inherent in the font. 

/* Set the font and add software styling to the text if I asked for 

a style in OpenFont ( ) and didn't get it. Because most Amiga fonts 
do not have styling built into them (with the exception of the CG 
outline fonts) , if the user selected some kind of styling for the 
text, it will have to be added algorithmically by calling 
SetSoftStyleO . 

*/ 

if (myf ont = OpenDiskFont (mytextattr) ) 

{ 

SetFont (myrastport , myf ont) ; 

SetSof tStyle (myrastport, 

mytextattr . ta_Style * myf ont->tf_Style, 
(FSF BOLD I FSF UNDERLINED I FSF ITALIC) ) ; 



} 



CloseFont (myf ont) ; 
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Does the Text Fit ? 

The Text() function renders its text on a single horizontal line without considering whether or not the text it renders 
will actually fit in the visible portion of the display area. Although for some applications this behavior is 
acceptable, other applications, for example a word processor, need to render all of their text where the user can 
see it. These applications need to measure the display area to determine how much text can fit along a given 
baseline. The graphics. library contains several functions that perform some of the necessary measurements: 

WORD TextLength( struct RastPort *my_rp, STRPTR mystring, ULONG mycount ); 



void TextExtent ( struct RastPort *my_rp, STRPTR mystring, LONG mycount, 
struct TextExtent *textExtent ) ; 

void FontExtent ( struct TextFont *font, struct TextExtent *fontExtent ); 

ULONG TextFit ( struct RastPort *rp, STRPTR mystring, ULONG strLen, 

struct TextExtent *textExtent , struct TextExtent *constrainingExtent , 
LONG strDirection, ULONG constrainingBitWidth, ULONG constrainingBitHeight 
) ; 

The TextLength() function is intended to mimic the Text() function without rendering the text. Using the exact 
same parameters as the Text() function, TextLength() returns the change in my_rp's current X position 
(my_rp.cp_x) that would result if the text had been rendered using the Text() function. As in Text(), the mycount 
parameter tells how many characters of mystring to measure. 

Some fonts have characters that intrinsically render outside of the normal rectangular bounds. This can result for 
example, from the Amiga's version of kerning (which is discussed later in this chapter) or from algorithmic 
italicizing. In such cases, TextLength() is insufficient for determining whether a text string can fit within a given 
rectangular bounds. 

The TextExtent() function offers a more complete measurement of a string than the TextLength() function. 
TextExtent(), which was introduced in Release 2, fills in the TextExtent structure passed to it based on the 
current rendering settings in my_rp. 

The TextExtent structure <graphics/text.h>) supplies the dimensions of mystring's bounding box: 

struct TextExtent { 

UWORD te_Width; /* same as TextLength */ 

UWORD te_Height; /* same as tf_YSize */ 

struct Rectangle te_Extent; /* relative to CP */ 

} ; 

The Rectangle structure (from <graphics/gfx.h>): 

struct Rectangle 

{ 

WORD MinX,MinY; 
WORD MaxX , MaxY ; 

}; 
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TextExtent() fills in the TextExtent as follows: 

te_Width 

the same value returned by TextLength(). 

te_Height 

the font's Y size. 

te_Extent.MinX 

the pixel offset from the rastport's current X position to the left side of the bounding box defined by the 
rectangle structure. Normally, this is zero. 

te_Extent.MinY 

the distance in pixels from the baseline to the top of the bounding box. 

te_Extent.MaxX 

the pixel offset from the rastport's current X position to the right side of the bounding box. Normally, 
this is te_Width - 1 . 

te_Extent.MaxY 

the distance from the baseline to the bottom of the bounding box. 



The FontExtent() function is similar to the TextExtentQ function. It fills in a TextExtent structure that describes 
the bounding box of the largest possible single character in a particular open font, including the effects of kerning. 
Because the FontExtent() function looks at an open DiskFont structure rather than a rastport to figure out values 
of the TextExtent structure, it cannot consider the effects of algorithmic styling. Like TextExtent(), FontExtent() 
was introduced in Release 2, so it is not available under the 1 .3 or earlier OS releases. 

The TextFit() function looks at a string and returns the number of characters of the string that will fit into a given 
rectangular bounds. TextFit() takes the current rastport rendering settings into consideration when measuring the 
text. Its parameters (from the prototype above) are: 

my_rp tells which rastport to get the rendering attributes from 

mystring the string to "fit" 

strLen number of characters of mystring to "fit" 

constrainingExtent a TextExtent describing the bounding box in which to "fit" mystring 

strDirection the offset to add to the string pointer to get to the next character in mystring 

(can be negative) 
constrainingBitWidth an alternative way to specify the width of the bounding box in which to "fit" 

mystring 
constrainingBitHeight an alternative way to specify the height of the bounding box in which to "fit" 

mystring 

TextFitQ will only pay attention to the constrainingBitWidth and constrainingBitHeight fields if 
constrainingExtent is NULL. 

Text Measuring Example 

The following example, measuretext.c, opens a window on the default publich screen and renders the contents of 
an ASCII file into the window. It uses TextFit() to measure how much of the line of text will fit across the window. 
If the entire line dosn't fit, measuretext will wrap the remainder of the line into the rows that follow. This example 
makes use of an ASL font requester, letting the user choose the font, style, size, drawing mode, and color. 
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;/* MeasureText . c - Execute me to compile me with Lattice 5.10a 

LC -bo -cfistq -v -y - j 73 MeasureText . c 

Blink FROM LIB:c.o, MeasureText . o TO MeasureText LIBRARY LIB : LC . lib, LIB : Amiga . lib 

quit ; 

* * 

** The following example, measuretext.c, opens a window on the default 
** public screen and renders the contents of an ASCII file into the 
** window. It uses TextFitO to measure how much of a line of text will 
** fit across the window. If the entire line doesn't fit, measuretext 
** will wrap the remainder of the line into the rows that follow. This 
** example makes use of an ASL font requester, letting the user choose 
** the font, style, size, drawing mode, and color. 

*/ 

#define INTUITION_IOBSOLETE_H 
#include <dos/dos.h> 
#include <dos/dosextens .h> 
#include <graphics/text . h> 
#include <graphics/rastport . h> 
#include <intuition/intuition.h> 
#include <exec/libraries . h> 

#include <clib/alib_stdio_protos . h> 
#include <clib/graphics_protos . h> 
#include <clib/intuition_protos . h> 
#include <clib/diskf ont_protos . h> 
#include <clib/dos_protos . h> 
#include <clib/exec_protos . h> 
#include <clib/asl_protos . h> 

#ifdef LATTICE 

int CXBRK(void) { return(O); } /* Disable Lattice CTRL/C handling */ 

int chkabort (void) { return(O); } 

#endif 

#define BUFSIZE 32768 



UBYTE *vers ■ "\0$VER: MeasureText 3 7.1"; 

UBYTE buf fer [BUFSIZE] ; 

void MainLoop (void) ; 
void EOP (void) ; 

struct Library *IntuitionBase, *GfxBase, *Diskf ontBase, *AslBase; 

BPTR myfile; 

UWORD wtbarheight ; 

struct FontRequester *fr; 

struct TextFont *myfont; 

struct Window *w; 

struct RastPort *myrp; 

struct Task *mytask; 

void main(int argc, char **argv) 

{ 

struct TextAttr myta; 

if (argc == 2) 

{ 

if (myfile = Open (argv [1] , MODE_OLDFILE) ) /* Open the file to print out. */ 

{ 

if (Diskf ontBase = OpenLibrary ( "diskfont . library" , 37L) ) /* Open the libraries. */ 

{ 

if (IntuitionBase = OpenLibrary ( "intuition. library" , 37L) ) 

{ 

if (GfxBase = OpenLibrary ( "graphics . library" , 37L) ) 

{ 

if (AslBase = OpenLibrary ( "asl . library" , 37L) ) 

{ 

if (fr = (struct FontRequester *) /* Open an ASL font requester */ 

AllocAslRequestTags (ASL_FontRequest , 

/* Supply initial values for requester */ 

ASL_FontName , (ULONG) "topaz . font " , 

ASL_FontHeight , 11L, 

ASL_FontStyles, FSF_BOLD | FSF_ITALIC, 

ASL_FrontPen, OxOlL, 

ASL_BackPen, 0x0 OL, 

/* Give us all the gadgetry */ 
ASL_FuncFlags, FONF_FRONTCOLOR | FONF_BACKCOLOR | 

FONF_DRAWMODE | FONF_STYLES , 
TAG_DONE) ) 

{ 

/* Pop up the requester */ 
if (AslRequest (f r, OL) ) 

{ 

myta.ta_Name = f r->f o_Attr . ta_Name; /* extract the font and */ 

myta. ta_YSize = f r->f o_Attr . ta_YSize 

myta. ta_Style = f r->f o_Attr . ta_Style 

myta. ta_Flags = f r->f o_Attr . ta_Flags 



/* display attributes */ 
/* from the FontRequest */ 
/* structure. */ 



if (myfont = OpenDiskFont (&myta) ) 

{ 

if (w = OpenWindowTags (NULL, WA_SizeGadget , TRUE, 

WA_MinWidth, 2 00, 

WA_MinHeight , 200, 

WA_DragBar , TRUE , 

WA_DepthGadget , TRUE , 

WA_Title, (ULONG) argv [1] , 
TAG_DONE) ) 

{ 

myrp = w->RPort; 

/* figure out where the baseline of the uppermost line should be. */ 

wtbarheight = w->WScreen->BarHeight + myf ont->tf_Baseline + 2 ; 

/* Set the font and add software styling to the text if I asked for it */ 
/* in OpenFont ( ) and didn't get it. Because most Amiga fonts do not */ 
/* have styling built into them (with the exception of the CG outline */ 



/* fonts) , if the user selected some kind of styling for the text, it */ 
/* will to be added algorithmically by calling SetSof tStyle ( ) . */ 

SetFont (myrp, myfont); 

SetSof tStyle (myrp, myta. ta_Style A myf ont->tf_Style, 

(FSF_BOLD | FSF_UNDERLINED | FSF_ITALIC) ) ; 
SetDrMd (myrp, f r->f o_DrawMode) ; 
SetAPen (myrp, fr->fo_FrontPen) ; 
SetBPen (myrp, fr->fo_BackPen) ; 

Move (myrp, w->WScreen->WBorLef t , wtbarheight) ; 
mytask = FindTask (NULL) ; 

MainLoop ( ) ; 

Delay (25) ; /* short delay to give user a chance to */ 

CloseWindow (w) ; /* see the text before it goes away. */ 

} 

CloseFont (myfont) ; 

} 
} 
else 

VPrintf ( "Request Cancelled\n" , NULL); 
FreeAslRequest (fr) ; 

} 

CloseLibrary (AslBase) ; 

} 

CloseLibrary (Gf xBase) ; 

} 

CloseLibrary (IntuitionBase) ; 

} 

CloseLibrary (Diskf ontBase) ; 

} 

Close (myf ile) ; 

} 
} 

else 

VPrintf ( "template : MeasureText <file name>\n", NULL); 
} 

void MainLoop (void) 

{ 

struct TextExtent resulttextent ; 

LONG fit, actual, count, printable, crrts; 

BOOL aok = TRUE; 

while (((actual = Read(myfile, buffer, BUFSIZE) ) > 0) && aok) /*while there's something to*/ 
{ /* read, fill the buffer. */ 

count = ; 

while (count < actual) 

{ 

crrts = ; 

while ( ( (buff er [count] < myf ont->tf_LoChar) | | /* skip non-printable characters, but */ 
(buffer [count] > myfont - >tf_HiChar) ) && /* account for newline characters. */ 
(count < actual) ) 

{ 

if (buffer [count] == '\012') crrts++; /* is this character a newline? if it is, bump */ 
count ++; /* up the newline count. */ 

} 

if (crrts > 0) /* if there where any newlines, be sure to display them. */ 

{ 

Move(myrp, w->BorderLef t , myrp->cp_y + (crrts * (myf ont->tf_YSize + 1) ) ) ; 

EOP ( ) ; /* did we go past the end of the page? */ 

} 

printable = count ; 

while ( (buff er [printable] >= myf ont->tf_LoChar) && /* find the next non-printables */ 
(buff er [printable] <= myf ont->tf_HiChar) && 



(printable < actual) ) 

{ 

printable++ ; 
} /* print the string of printable characters wrapping */ 

while (count < printable) /* lines to the beginning of the next line as needed. */ 

{ 

/* how many characters in the current string of printable characters will fit */ 
/* between the rastport's current X position and the edge of the window? */ 
fit = TextFit ( myrp, & (buff er [count] ) , 

(printable - count), &resulttextent , 

NULL , 1 , 

(w->Width - (myrp->cp_x + w->BorderLef t + w->BorderRight) ) , 

myf ont->tf_YSize +1 ) ; 
if ( fit == ) 

{ 

/* nothing else fits on this line, need to wrap to the next line. */ 

Move(myrp, w->BorderLef t , myrp->cp_y + myf ont->tf_YSize + 1); 

} 
else 

{ 

Text (myrp, & (buffer [count] ) , fit) ; 
count += fit; 

} 

EOP ( ) ; 

} 

if (mytask->tc_SigRecvd & SIGBREAKF_CTRL_C) /* did the user hit CTRL-C (the shell */ 
{ /* window has to receive the CTRL-C)? */ 

aok = FALSE; 

VPrintf ("Ctrl-C Break\n", NULL); 
count = BUFSIZE + 1; 
} 
} 
} 
if (actual < 0) 

VPrintf ( "Error while reading\n", NULL); 
} 

void EOP (void) 

{ 

if (myrp->cp_y > (w->Height- (w->BorderBottom +2))) /*If we reached page bottom, clear the*/ 
{ /* rastport and move back to the top.*/ 

Delay (25) ; 

SetAPen(myrp, 0) ; 

RectFill (myrp, (LONG) w->BorderLef t , (LONG) w->BorderTop, w->Width- (w->BorderRight + 1), 

w->Height - (w->BorderBottom +1) ) ; 
SetAPen(myrp, 1) ; 

Move (myrp, w->BorderLef t + 1, wtbarheight) ; 
SetAPen (myrp, fr->fo_FrontPen) ; 
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Font Scaling and the Aspect Ratio 

The Release 2 OS offers a significant improvement over the Amiga's previous font resources: it now has the 
ability to scale fonts to new sizes and dimensions. This means, if the diskfont. library can't find the font size an 
application requests, it can create a new bitmap font by scaling the bitmap of a different size font in the same font 
family. The 2.04 (V37) release of the OS improved upon the diskfont. library's font scaling ability so the Amiga 
now can utilize AGFA Compugraphic outline fonts, yielding scalable fonts that don't have the exaggerated jagged 
edges inherent in bitmap scaling. 

The best thing about the Amiga's font scaling is that its addition to the system is completely invisible to an 
application program. Because the diskfont. library takes care of all the font scaling, any program that uses 
OpenDiskFont() to open a font can have scalable fonts available to it. For simple scaling, the programming 
interface is the same using Release 2 as it was under 1 .3. 



However, there is one feature of the Release 2 diskfont.library that the 1 .3 programming interface cannot handle. 
When scaling a font (either from an outline or from another bitmap), the Release 2 diskfont.library can adjust the 
width of a font's glyphs according to an aspect ratio passed to OpenDiskFont(). A font glyph is the graphical 
representations associated with each symbol or character of a font. 

The aspect ratio refers to the shape of the pixels that make up the bitmap that diskfont.library creates when it 
scales a font. This ratio is the width of a pixel to the height of the pixel (XWidth/ YWidth). The diskfont.library 
uses this ratio to figure out how wide to make the font glyphs so that the look of a font's glyphs will be the same 
on display modes with very different aspect ratios. 

To add this new feature, several changes to the OS were necessary: 

1 ) The OS needed to be able to store an aspect ratio for any font loaded into the system list. 

2) The structures that diskfont.library uses to store bitmap fonts on disk had to be updated so they can 
store the aspect ratio a font was designed for. 

3) The way in which an application requests fonts from diskfont.library had to be altered so that an 
application could ask for a specific aspect ratio. 

For the diskfont.library to be able to scale a font to a new aspect ratio, it needs to know what the font's current 
aspect ratio is. The Amiga gets the aspect ratio of a font currently in the system list from an extension to the 
TextFont structure called (oddly enough) TextFontExtension. Under Release 2, when the system opens a new 
font (and there is sufficient memory), it creates this extension. 

A font's TextFont structure contains a pointer to its associated TextFontExtension. While the font is opened, the 
TextFont's tf_Message.mn_ReplyPort field points to a font's TextFontExtension. The <graphics/text.h> 
include file #defines tf_Message.mn_ReplyPort as tf_Extension. 

The TextFontExtension structure contains only one field of interest: a pointer to a tag list associated with this 
font: 

struct Tagltem *tfe_Tags; /* Text Tags for the font */ 

If a font has an aspect ratio associated with it, the OS stores the aspect ratio as a tag/value pair in the tfe_Tags 
tag list. 
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The TADeviceDPI tag holds a font's aspect ratio. The data portion of the TADeviceDPI tag contains an X DPI 
(dots per inch) value in its upper word and a Y DPI value in its lower word. These values are unsigned words 
(UWORD). At present, these values do not necessarily reflect the font's true X and Y DPI, so their specific values 
are not relevant. At present, only the ratio of the X aspect to the Y aspect is important (more on this later in the 
article). 

Notice that the X and Y DPI values are not aspect values. The X and Y aspect values are the reciprocals of the X 
and Y DPI values, respectively: 

XDPI = 1/XAspect 
YDPI = 1/YAspect 

so, the aspect ratio is YDPI/XDPI, not XDPI/YDPI. 

Before accessing the tag list, an application should make sure that this font has a corresponding 
TextFontExtension. The ExtendFontQ function will return a value of TRUE if this font already has an extension 
or ExtendFont() was able to create an extension for this font. 

The Amiga has a place to store a font's X and Y DPI values once the font is loaded into memory, but where do 
these X and Y values come from? A font's X and Y DPI values can come from several sources. The X and Y DPI 
can come from a font's disk-based representation, or it can be set by the programmer. 

For the traditional Amiga bitmap fonts, in order to store the X and Y DPI values in a bitmap font's ".font" file, the 
structures that make up the ".font" file had to be expanded slightly. See the discussion of the 
FontContentsHeader structure in the "Composition of a Bitmap Font on Disk" section later in this chapter for 



more information. Currently, out of all the system standard bitmap fonts (those loaded from bitmaps on disk or 
ROM, not scaled from a bitmap or outline), only one has a built in aspect ratio: Topaz-9. 

For the Compugraphic outline fonts, the X and Y DPI values are built into the font outline. Because the format of 
the Compugraphic outline fonts is proprietary, information about their layout is available only from AGFA 
Compugraphic. For most people, the format of the outline fonts is not important, as the diskfont. library handles 
converting the fonts to an Amiga-usable form. 

The other place where a font can get an aspect ratio is an application. When an application opens a font with 
OpenDiskFont(), it can supply the TA_DeviceDPI tag that the diskfont.library uses to scale (if necessary) the font 
according to the aspect ratio. To do so, an application has to pass OpenDiskFont() an extended version of the 
TextAttr structure called the TTextAttr: 

struct TTextAttr { 

STRPTR tta Name; /* name of the font */ 



UWORD tta_YSize 
UBYTE tta_Style 
UBYTE tta_Flags 



/* height of the font */ 
/* intrinsic font style */ 
/* font preferences and flags */ 



struct Tagltem *tta_Tags; /* extended attributes */ 

} ; 

The TextAttr and the TTextAttr are identical except that the tta_Tags field points to a tag list where you place 
your TA_DeviceDPI tag. To tell OpenDiskFontQ that it has a TTextAttr structure rather than a TextAttr 
structure, set the FSF_TAGGED bit in the tta_Style field. 

682 Amiga ROM Kernel Reference Manual: Libraries 

For example, to ask for Topaz-9 scaled to an aspect ratio of 75 to 50 the code might look something like this: 

#define MYXDPI (75L << 16) 
#define MYYDPI (50L) 

struct TTextAttr mytta = { 
"topaz .font" , 9, 
FSF_TAGGED, 0, NULL 

}; 

struct Tagltem tagitem[2] ; 
struct TextFont *myf ont ; 
ULONG dpivalue; 



tagitem[0] . ti_tag = TA_DeviceDPI ; 
tagitem[0] . ti_Data = MYXDPI | MYYDPI; 
tagitem[l] . ti_tag = TAG_END; 
mytta . tta_tags = tagitem; 



if (myfont = OpenDiskFont (&mytta) ) 

{ 

dpi = GetTagData (TA_DeviceDPI, 
OL, 
((struct TextFontExtension *) (myf ont->tf_Extension) ) ->tf e_Tags) ; 
if (dpi) printf ("XDPI = %d YDPI = %d\n", 
((dpi & OxFFFFOOOO) >>16) , 
(dpi & OxOOOOFFFF) ) ; 
... /* Blah Blah print blah */ 

CloseFont (myf ont) ; 
} 



Some Things to Look Out For 

One misleading thing about the TA_DeviceDPI tag is that its name implies that the diskfont.library is going to 
scale the font glyphs according to an actual DPI (dots per inch) value. As far as scaling is concerned, this tag 
serves only as a way to specify the aspect ratio, so the actual values of the X and Y elements are not important, 
just the ratio of one to the other. A font glyph will look the same if the ratio is 2:1 or 200:100 as these two ratios 
are equal. 

To makes things a little more complicated, when diskfont.library scales a bitmap font using an aspect ratio, the X 
and Y DPI values that the OS stores in the font's TextFontExtension are identical to the X and Y DPI values 
passed in the TA_DeviceDPI tag. This means the system can associate an X and Y DPI value to an open font 
size that is very different from the font size's actual X and Y DPI. For this reason, applications should not use 
these values as real DPI values. Instead, only use them to calculate a ratio. 

For the Compugraphic outline fonts, things are a little different. The X and Y DPI values are built into the font 
outline and reflect a true X and Y DPI. When the diskfont.library creates a font from an outline, scaling it 
according to an application-supplied aspect ratio, diskfont.library does not change the Y DPI setting. Instead, it 
calculates a new X DPI based on the font's Y DPI value and the aspect ratio passed in the TA_DeviceDPI tag. It 
does this because the Amiga thinks of a font size as being a height in pixels. If an application was able to change 
the true Y DPI of a font, the diskfont.library would end up creating font sizes that were much larger or smaller than 
the YSize the application asked for. If an application needs to scale a font according to height as well as width, 
the application can adjust the value of the YSize it asks for in the TTextAttr. 
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As mentioned earlier, almost all of the system standard bitmap fonts do not have a built in aspect ratio. This 
means that if an application loads one of these bitmap fonts without supplying an aspect ratio, the system will not 
put a TADeviceDPI tag in the font's TextFontExtension: the font will not have an aspect ratio. If a font size that 
is already in the system font list does not have an associated X and Y DPI, the diskfont.library cannot create a 
new font of the same size with a different aspect ratio. 

The reason for this is the diskfont.library cannot tell the difference between two instances of the same font size 
where one has an aspect ratio and the other does not. Because diskfont.library cannot see this difference, when 
an application asks, for example, for Topaz-8 with an aspect ratio of 2:1 , OpenDiskFont() first looks through the 
system list to see if that font is loaded. OpenDiskFont() happens to find the ROM font Topaz-8 in the system font 
list, which has no X and Y DPI. Because it cannot see the difference, diskfont.library thinks it has found what it 
was looking for, so it does not create a new Topaz-8 with an aspect ratio of 2:1 , and instead opens the Topaz-8 
with no aspect ratio. 

This also causes problems for programs that do not ask for a specific aspect ratio. When an application asks for 
a font size without specifying an aspect ratio, OpenDiskFont() will not consider the aspect ratios of fonts in the 
system font list when it is looking for a matching font. If a font of the same font and style is already in the system 
font list, even though it may have a wildly distorted aspect ratio, OpenDiskFont() will return the font already in the 
system rather than creating a new one. 

Font Aspect Ratio Example 

The following example, cliptext.c, renders the contents of a text file to a Workbench window. This example gets 
the new aspect ratio for a font by asking the display database what the aspect ratio of the current display mode is. 

;/* cliptext.c - Execute me to compile me with Lattice 5.10a 

LC -cfistq -v -y - j 73 cliptext.c 

Blink FROM LIB : c . o, cliptext . o TO cliptext LIBRARY LIB : LC . lib, LIB : Amiga . lib 

quit ; 

** The following example, cliptext.c, renders the contents of a text 

** file to a Workbench window. This example gets the new aspect ratio 

** for a font by asking the display database what the aspect ratio of 
** the current display mode is. 

*/ 

#include <exec/types . h> 
#include <dos/rdargs .h> 
#include <dos/dosextens .h> 
#include <intuition/intuition.h> 



#include <graphics/text .h> 
# include <graphi cs/di splay inf o.h> 
#include <graphics/regions . h> 
#include <graphics/gfx.h> 
#include <libraries/diskf ont . h> 
#include <libraries/diskf onttag.h> 
#include <utility/tagitem.h> 
#include <clib/exec_protos . h> 
#include <clib/dos_protos . h> 
#include <clib/layers_protos . h> 
#include <clib/alib_stdio_protos . h> 
#include <clib/intuition_protos . h> 
#include <clib/graphics_protos . h> 
#include <clib/diskf ont_protos . h> 

#ifdef LATTICE 

int CXBRK(void) { return(O); } /* Disable Lattice CTRL/C handling */ 

int chkabort (void) { return(O); } 

#endif 



UBYTE *vers 



'\0$VER: cliptext 37.2' 



#define BUFSIZE 4096 

# define FONT_NAME 

#define FONT_SIZE 1 

#define FILE_NAME 2 

#define JAM_MODE 3 

#define XASP 4 

#define YASP 5 

#define NUM_ARGS 6 
#define DEFAULTFONTSIZE 11L 

#define DE FAULT JAMMODE OL 

#define DEFAULTXASP OL 

#define DEFAULTYASP OL 

void MainLoop (void) ; 



LONG args [NUM_ARGS] ; 
struct Tagltem tagitem[2] ; 
UBYTE buffer [BUFSIZE] ; 
BPTR myfile; 

struct Library *Diskf ontBase, 
struct IntuiMessage *mymsg; 
struct Drawlnfo *mydrawinfo; 
struct Window *mywin; 
struct RastPort *myrp; 
struct TTextAttr myta; 
struct TextFont *myfont; 
struct Rectangle myrectangle; 
struct Region *new_region; 



*IntuitionBase, *LayersBase, *GfxBase; 



void main (int argc, char **argv) 

{ 

struct RDArgs *myrda; 
struct Displaylnfo mydi ; 
ULONG mymodeid; 



LONG 
LONG 
LONG 
LONG 
args 
args 
args 
args 
args 
args 



mydef aultf ontsize = 
mydefaultJAMMode = 
mydef aultXASP = OL; 
mydef aultYASP = OL; 



[FONTJSTAME] 

[FONT_SIZE] 

[FILE_NAME] 

[JAM_MODE] 

[XASP] 

[YASP] 



(LONG) 
(LONG) 
(LONG) 
(LONG) 
(LONG) 
(LONG) 



DEFAULTFONTSIZE ; 
DEFAULT JAMMODE ; 



"topaz . font" ; 
&mydef aultf ontsize ; 
"s : startup-sequence" 
&mydef ault JAMMode ; 
&mydef aultXASP ; 
&mydef aultYASP; 



/* dos. library standard command line parsing--See the dos. library Autodoc for details */ 
if (myrda ■ ReadArgs ( "FontName, FontSize/N, FileName, Jam/N,XASP/N, YASP/N\n" , args, NULL)) 



if (myfile = Open ( (UBYTE * ) args [FILE_NAME] , MODEJOLDFILE) ) /* Open the file to display.*/ 



{ 

if (Diskf ontBase = OpenLibrary ( "diskfont . library" , 37L) ) /* Open the libraries. */ 

{ 

if (IntuitionBase = OpenLibrary ( "intuition. library" , 37L) ) 

{ 

if (GfxBase = OpenLibrary ( "graphics . library" , 37L) ) 

{ 

if (LayersBase = OpenLibrary ( "layers . library" , 37L) ) 

{ 

if (mywin = OpenWindowTags (NULL, /* Open that window. */ 

WA_MinWidth, 100, /* This application wants to hear about three */ 
WA_MinHeight , 100, /* things: 1) When the user clicks the window's */ 
WA_SmartRef resh, TRUE, /* close gadget, 2) when the user starts to */ 
WA_SizeGadget , TRUE, /* resize the window, 3) and when the user has */ 
WA_CloseGadget , TRUE, /* finished resizing the window. */ 

WA_IDCMP, IDCMP_CLOSEWINDOW | IDCMP_NEWSIZE | IDCMP_SIZEVERIFY , 
WA_DragBar , TRUE , 
WA_DepthGadget, TRUE, 

WA_Title, (ULONG)args [FILE_NAME] , 
TAG_END) ) 

{ 

tagitem[0] . ti_Tag = OT_DeviceDPI ; 

/* See if there is a non-zero value in the XASP or YASP fields. Diskf ont . library */ 
/* will get a divide by zero GURU if you give it a zero XDPI or YDPI value. */ 

/* if there is a zero value in one of them. . . */ 

if ( ( (* (ULONG *)args [XASP] ) ==0) || ( (* (ULONG * ) args [YASP] ) == 0) ) 

{ 

/* . . .then use the aspect ratio of the current display as a default. . . */ 
mymodeid = GetVPModelD (& (mywin->WScreen->ViewPort) ) ; 
if (GetDisplaylnfoDatat NULL, (UBYTE * ) &mydi , 

sizeof (struct Displaylnfo) , DTAG_DISP, mymodeid)) 

{ 

mydef aultXASP = mydi . Resolution .x; 

mydef aultYASP = mydi .Resolution. y; 

printf("XAsp = %ld YAsp = %ld\n" , mydef aultXASP, mydef aultYASP) ; 

/* Notice that the X and Y get _swapped_ to keep the look of the */ 

/* font glyphs the same using screens with different aspect ratios. */ 

args [YASP] = (LONG) &mydef aultXASP, • 

args [XASP] = (LONG) &my default YASP; 

} 

else /* . . .unless something is preventing us from getting the screen */ 
/* screens resolution. In that case, forget about the DPI tag. */ 
tagitem[0] . ti_Tag = TAG_END; 

} 
/* Here we have to put the X and Y DPI into the OT_DeviceDPI tags data field. */ 
/* THESE ARE NOT REAL X AND Y DPI VALUES FOR THIS FONT OR DISPLAY. They only */ 
/* serve to supply the diskf ont . library with values to calculate the aspect */ 
/* ratio. The X value gets stored in the upper word of the tag value and the Y*/ 
/* DPI gets stored in the lower word. Because ReadArgs ( ) stores the _address_ */ 
/* of integers it gets from the command line, you have to dereference the */ 
/* pointer it puts into the argument array, which results in some ugly casting.*/ 

tagitem[0] .ti_Data = (ULONG) ( ( (UWORD) *( (ULONG *)args[XASP] ) << 16) | 

( (UWORD) *( (ULONG *) args [YASP] ) ) ); 
tagitem[l] .ti_Tag = TAG_END; 

myta.ttaJSTame = (STRPTR) args [FONT_NAME] ; /* Set up the TTextAttr */ 
myta.tta_YSize = * ( (LONG * ) args [FONT_SIZE] ) ; /* structure to match the */ 
myta.tta_Style = FSF_TAGGED; /* font the user requested. */ 

myta. tta_Flags = 0L; 
myta. tta_Tags = tagitem; 

if (myfont = OpenDiskFont (&myta) ) /* open that font */ 

{ 

/* This is for the layers . library clipping region that gets attached to the */ 

/* window. This prevents the application from unnecessarily rendering beyond */ 

myrectangle .MinX = mywin- >BorderLef t ; /* the bounds of the inner part of */ 

myrectangle .MinY = mywin- >BorderTop; /* the window. For now, you can */ 

myrectangle .MaxX = mywin->Width - /* ignore the layers stuff if you are */ 

(mywin- >BorderRight + 1) ; /* just interested in learning about */ 



myrectangle .MaxY = mywin->Height - /* using text. For more information */ 
(mywin->BorderBottom + 1) ; /* on clipping regions and layers, see */ 

/* the Layers chapter of this manual. */ 

if (new_region = NewRegionO) /* more layers stuff */ 

{ 

if (OrRectRegion (new_region, &myrectangle) ) ; /* Even more layers stuff */ 

{ 

InstallClipRegion (mywin->WLayer , new_region) ; 

/* Obtain a pointer to the window's rastport and set up some of the */ 
myrp = mywin->RPort ; /* rastport attributes. This example obtains the */ 
SetFont (myrp, myfont) ; /*text pen for the window's screen using */ 

if (mydrawinfo =GetScreenDrawInf o (mywin->WScreen) ) /* GetScreenDrawInf o ( ) */ 

{ 

SetAPen(myrp, mydrawinfo- >dri_Pens [TEXTPEN] ) ; 
FreeScreenDrawInf o (mywin->WScreen, mydrawinfo) ; 

} 

SetDrMdtmyrp, (BYTE) (* ( (LONG * ) args [ JAM_MODE] ) ) ) ; 

MainLoop ( ) ; 

} 

DisposeRegion (new_region) ; 

} 

CloseFont (myfont) ; 

} 

CloseWindow (mywin) ; 

} 

CloseLibrary (LayersBase) ; 

} 

CloseLibrary (Gf xBase) ; 

} 

CloseLibrary (IntuitionBase) ; 

} 

CloseLibrary (Diskf ontBase) ; 

} 

Close (myf ile) ; 

} 

FreeArgs (myrda) ; 

} 

else VPrintf ( "Error parsing arguments\n" , NULL); 

} 

void MainLoop (void) 

{ 

LONG count, actual, position; 

BOOL aok = TRUE, waitf ornewsize = FALSE; 

struct Task *mytask; 

mytask = FindTask (NULL) ; 

Move (myrp, mywin- >BorderLeft + 1, mywin- >BorderTop + myf ont->tf_YSize + 1) ; 

while (((actual = Read(myfile, buffer, BUFSIZE) ) > 0) && aok) /*While there's something */ 
{ /* to read, fill the buffer. */ 

position = 0; 

count = ; 

while (position <= actual) 

{ 

if ( ! (waitf ornewsize) ) 

{ 

while ( ( (buff er [count] >= myf ont->tf_LoChar) && 

(buffer [count] <= myfont - >tf_HiChar) ) && (count <= actual) ) 
count ++ ; 

Text (myrp, & (buff er [position] ) , (count) -position) ; 

while ( ( (buff er [count] < myf ont->tf_LoChar) | 

(buffer [count] > myfont - >tf_HiChar) ) && (count <= actual) ) 

{ 

if (buffer [count] == OxOA) 

Move (myrp, mywin- >BorderLeft, myrp->cp_y + myf ont->tf_YSize + 1) ; 
count ++ ; 



position = count; 

} 

else WaitPort (mywin->UserPort) ; 

while (mymsg = (struct IntuiMessage *) GetMsg (mywin->UserPort) ) 

{ 

if (mymsg- >Class == IDCMP_CLOSEWINDOW) /* The user clicked the close gadget */ 

{ 

aok = FALSE; 

position = actual + 1; 

ReplyMsg ( (struct Message *)mymsg); 
} /* The user picked up the */ 

else if (mymsg- >Class == IDCMP_SIZEVERIFY) /* window's sizing gadget */ 

{ 

/* When the user has picked up the window's sizing gadget when the */ 

/* IDCMP_SIZEVERIFY flag is set, the application has to reply to this message*/ 
/* to tell Intuition to allow the user to move the sizing gadget and resize */ 
/* the window. The reason for using this here is because the user can resize*/ 
/* the window while cliptext.c is rendering text to the window. Cliptext.c */ 
/* has to stop rendering text when it receives an IDCMP_SIZEVERIFY message. */ 

/* */ 

/* if this example had instead asked to hear about IDCMP events that could */ 

/* take place between SIZEVERIFY and NEWSIZE events (especially INTUITICKS) , */ 

/* it should turn off those events here using ModifylDCMP ( ) . */ 

/* " ' */ 

/* After we allow the user to resize the window, we cannot write into the */ 

/* window until the user has finished resizing it because we need the */ 

/* window's new size to adjust the clipping area. Specifically, we have */ 

/* to wait for an IDCMP_NEWSIZE message which Intuition will send when the */ 

/* user lets go of the resize gadget. For now, we set the waitf ornewsize */ 

/* flag to stop rendering until we get that NEWSIZE message. */ 

waitf ornewsize = TRUE; 
WaitBlit () ; 

ReplyMsg ( (struct Message *)mymsg); /* The blitter is done, let the */ 
} /* user resize the window. */ 

else 

{ 

ReplyMsg ( (struct Message *)mymsg); 
waitf ornewsize = FALSE; 

/* The user has resized the window, so get the new window dimensions */ 
myrectangle .MinX = mywin->BorderLef t ; /* and readjust the layers */ 
myrectangle .MinY = mywin->BorderTop; /* clipping region accordingly. */ 
myrectangle .MaxX = mywin->Width - (mywin->BorderRight + 1) ; 
myrectangle .MaxY = mywin->Height - (mywin->BorderBottom + 1) ; 
InstallClipRegion (mywin->WLayer , NULL) ; 
ClearRegion (new_region) ; 
if (OrRectRegion (new_region, &myrectangle) ) 

InstallClipRegion (mywin->WLayer, new_region) ; 
else 

{ 

aok = FALSE; 
position = actual + 1; 
} 
} 
} 
if (mytask->tc_SigRecvd & SIGBREAKF_CTRL_C) /* Check for user break. */ 

{ 

aok = FALSE; 
position = actual + 1; 
} 

if (myrp->cp_y > (mywin->Height - (mywin->BorderBottom + 2)))/*if we reached the */ 

{ /* bottom of the page, clear the */ 

Delay (25) ; /* rastport and move back to the top*/ 

SetRast (myrp, 0) ; /* Set the entire rastport to color zero. This will not */ 
Move(myrp, /* the window borders because of the layers clipping. */ 

mywin->BorderLef t + 1, 
mywin->BorderTop + myf ont->tf_YSize + 1) ; 



if (actual < 0) VPrintf ( "Error while reading\n", NULL); 
} 

What Fonts Are Available? 

The diskfont. library function AvailFonts() fills in a memory area designated by you with a list of all of the fonts 
available to the system. AvailFonts() searches the AmigaDOS directory path currently assigned to FONTS: and 
locates all available fonts. If you haven't issued a DOS Assign command to change the FONTS: directory path, it 
defaults to the sys:fonts directory. 

LONG AvailFonts( struct Avail Font sHeader *mybuffer, LONG bufBytes, LONG flags ); 

AvailFonts() fills in a memory area, mybuffer, which is bufBytes bytes long, with an AvailFontsHeader structure: 

struct AvailFontsHeader { 

UWORD afh_NumEntries; /* number of AvailFonts elements */ 
/* struct AvailFonts afh_AF[], or struct TAvailFonts afh_TAF[]; */ 

}; 

This structure is followed by an array of AvailFonts structures with the number of entries in the array equal to 
afh_NumEntries: 

struct AvailFonts { 

UWORD af_Type; /* MEMORY, DISK, or SCALED */ 

struct TextAttr af_Attr; /* text attributes for font */ 

}; 
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Each AvailFonts structure describes a font available to the OS. The flags field lets AvailFonts() know which 
fonts you want to hear about. At present, there are four possible flags: 

AFF_MEMORY Create AvailFonts structures for all TextFont's currently in the system list. 

AFF_DISK Create AvailFonts structures for all TextFont's that are currently available from disk. 

AFF_SCALED Create AvailFonts structures for TextFont's that do not have their FPF_DESIGNED 
flag set. If the AFF_SCALED flag is not present, AvailFonts() will not create 
AvailFonts structures for fonts that have been scaled, which do not have the 
FPF_DESIGNED flag set. 

AFF_TAGGED These AvailFonts structures are really TAvailFonts structures. These structures 
were created for Release 2 to allow AvailFonts() to list tag values: 

struct TAvailFonts { 

UWORD taf_Type; /* MEMORY, DISK, or SCALED */ 

struct TTextAttr taf_Attr; /* text attributes for font */ 

}; 

Notice that AFF_MEMORY and AFF_DISK are not mutually exclusive; a font that is currently in memory may also 
be available for loading from disk. In this case, the font will appear twice in the array of AvailFonts (or 
TAvailFonts) structures. 

If AvailFontsQ fails without any major system problems, it will be because the buffer for the AvailFontsHeader 
structure was not big enough to contain all of the AvailFonts or TAvailFonts structures. In this case, 
AvailFontsQ returns the number of additional bytes that mybuffer needed to contain all of the TAvailFonts or 
AvailFonts structures. You can then use that return value to figure out how big the buffer needs to be, allocate 
that memory, and try AvailFonts() again: 

int af Shortage, afSize; 
struct AvailFontsHeader *afh; 



afSize = AvailFontS (af h, OL, AFF_MEMORY | AFF_DISK| AFF_SCALED | AFF_TAGGED) ; 
do 

{ 

afh = (struct AvailFontsHeader *) AllocMem(af Size, 0) ; 
if (afh) 

{ 

afShortage = Avail Fonts (afh, afSize, AFF_MEMORY| AFF_DISK| AFF_SCALED | AFF_TAGGED) ; 

if (afShortage) 

{ 

FreeMem (afh, afSize); 
afSize += afShortage; 
} 
} 
else 

{ 

fail ( "AllocMem of AvailFontS buffer afh failed\n"); 
break ; 

} 

} while (afShortage) ; /* if (afh) non-zero here, then: */ 

/* 1. it points to a valid AvailFontsHeader, */ 

/* 2. it must have FreeMem (afh, afSize) */ 

/* called for it after use. */ 

The following code, AvailFonts.c, uses AvailFonts() to find out what fonts are available to the system. It uses this 
information to open every available font (one at a time), print some information about the font (including the 
TA_DeviceDPI tag values if they are present), and renders a sample of the font into a clipping region. 
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;/* AvailFonts.c - Execute me to compile me with Lattice 5.10a 

LC -cfistq -v -y - j 73 AvailFonts.c 

Blink FROM LIB : c . o, AvailFontS . o TO AvailFontS LIBRARY LIB : LC . lib, LIB : Amiga . lib 

quit ;*/ 

#include <exec/types .h> 
#include <dos/rdargs .h> 
#include <dos/dosextens .h> 
#include <intuition/intuition.h> 
#include <intuition/screens .h> 
#include <graphics/text .h> 
# include <graphi cs/di splay inf o.h> 
#include <graphics/regions .h> 
#include <graphics/gfx.h> 
#include <libraries/diskf ont .h> 
#include <utility/tagitem.h> 
#include <clib/exec_protos .h> 
#include <clib/dos_protos .h> 
#include <clib/layers_protos .h> 
#include <clib/alib_stdio_protos .h> 
#include <clib/intuition_protos .h> 
#include <clib/graphics_protos .h> 
#include <clib/diskf ont_protos .h> 
#include <clib/utility_protos .h> 

#ifdef LATTICE 

int CXBRK(void) { return(O); } /* Disable Lattice CTRL/C handling */ 

int chkabort (void) { return (0); } 

#endif 

UBYTE *vers = "\0$VER: AvailFontS 36.3"; 

void MainLoop (void) ; 
ULONG StrLen (UBYTE *); 

struct stringstruct { 
UBYTE *string; 
LONG charcount ; 
WORD stringwidth; 



UBYTE *alphabetstring = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz" ; 

struct stringstruct fname, f height, XDPI, YDPI, entrynum; 

struct Library *Diskf ontBase, *IntuitionBase, *LayersBase, *GfxBase, *UtilityBase; 

struct Window *mywin; 

struct RastPort *mycliprp, myrp; 

struct Rectangle myrect; 

struct Region *new_region, *old_region; 

struct Drawlnfo *mydrawinfo; 

struct AvailFontsHeader *afh; 

LONG fontheight, alphabetcharcount; 

WORD stringwidth; 

void main(int argc, char **argv) 

{ 

struct TextFont *defaultfont = NULL; 

struct TextAttr def aultf ontattr = { "topaz . font " , 9, 0, }; 

LONG afsize, afshortage, cliprectside; 

fname. string = "Font Name: "; 
f height . string = "Font Height: "; 
XDPI. string = "X DPI: " ; 
YDPI. string = "Y DPI: "; 
entrynum. string = "Entry #: "; 

if (Diskf ontBase = OpenLibrary ( "diskfont . library" , 37L) ) /* Open the libraries. */ 

{ 

if (IntuitionBase = OpenLibrary ( "intuition. library" , 37L) ) 

{ 

if (GfxBase = OpenLibrary ( "graphics . library" , 37L) ) 

{ 

if (LayersBase = OpenLibrary ( "layers . library" , 37L) ) 

{ 

if (UtilityBase = OpenLibrary ( "utility . library" , 37L) ) 

{ 

if (mywin = OpenWindowTags (NULL, /* Open that window. */ 

WA_SmartRef resh, TRUE , 

WA_SizeGadget, FALSE, 

WA_CloseGadget , TRUE , 

WA_IDCMP, IDCMP_CLOSEWINDOW, 

WA_DragBar , TRUE , 

WA_DepthGadget , TRUE , 

WA_Title, (ULONG) "AvailFonts () example", 
TAG_END) ) 

{ 

myrp = * (mywin- >RPort) ; /* A structure assign: clone my window's Rastport. */ 

/* RastPort. This RastPort will be used to render */ 
/* the font specs, not the actual font sample. */ 

if (mydrawinfo = GetScreenDrawInfo (mywin- >WScreen) ) 

{ 

SetFont (&myrp, mydrawinfo- >dri_Font) ; 

myrect. MinX = mywin- >BorderLef t ; /* LAYOUT THE WINDOW */ 

myrect. MinY = mywin- >BorderTop; 

myrect. MaxX = mywin->Width - (mywin- >BorderRight + 1) ; 

myrect. MaxY = mywin->Height - (mywin- >BorderBottom + 1) ; 

cliprectside = (myrect. MaxX - myrect. MinX) / 20; 

fname . charcount = StrLen (fname . string) ; 

f height . charcount = StrLen (fheight . string) ; 

XDPI . charcount = StrLen (XDPI . string) ; 

YDPI . charcount = StrLen (YDPI . string) ; 

entrynum. charcount = StrLen (entrynum. string) ; 

alphabetcharcount = StrLen (alphabetstring) ; 

fontheight = (myrp. Font->tf_YSize) + 2; 

if (fontheight > ( (myrect .MaxY - myrect. MinY) / 6)) /*If the default screen */ 
{ /* font is more than one- */ 



def aultfont = OpenFont (&def aultf ontattr) ; /* sixth the size of the */ 
SetFont (&myrp, defaultfont) ; /* window, use topaz-9. */ 

fontheight - (myrp. Font->tf_YSize) + 2; 
} 

fname . stringwidth = TextLength (&myrp, (STRPTR) fname . string, fname . charcount) ; 
f height . stringwidth = TextLength (&myrp, (STRPTR) fheight . string, f height . charcount) ; 
XDPI .stringwidth = TextLength (&myrp, (STRPTR) XDPI . string, XDPI .charcount) ; 
YDPI .stringwidth = TextLength (&myrp, (STRPTR) YDPI . string, YDPI . charcount) ; 
entrynum. stringwidth = 

TextLength (&myrp, (STRPTR) entrynum. string, entrynum. charcount) ; 

stringwidth = fname . stringwidth; /* What is the largest string length? */ 
stringwidth = 

(fheight . stringwidth > stringwidth) ? fheight . stringwidth : stringwidth; 
stringwidth = (XDPI . stringwidth > stringwidth) ? XDPI . stringwidth : stringwidth; 
stringwidth = (YDPI . stringwidth > stringwidth) ? YDPI . stringwidth : stringwidth; 
stringwidth = 

(entrynum. stringwidth > stringwidth) ? entrynum. stringwidth : stringwidth; 
stringwidth += mywin->BorderLef t ; 

if (stringwidth < ( (myrect .MaxX-myrect .MinX) >> 1)) /* If the stringwidth is*/ 

{ /* more than half the viewing*/ 

SetAPen (&myrp, mydrawinf o->dri_Pens [TEXTPEN] ) ; /*area,quit because the */ 

SetDrMd(&myrp, JAM2); /* font is just too big. */ 

Move ( &myrp , myrect. MinX + 8 + stringwidth - fname . stringwidth, 

myrect. MinY + 4 + (myrp. Font->tf_Baseline) ) ; 
Text(&myrp, fname . string, fname . charcount) ; 

Move(&myrp, myrect. MinX + 8 + stringwidth - fheight . stringwidth, 

myrp.cp_y + fontheight); 
Text(&myrp, fheight . string, f height . charcount) ; 

Move(&myrp, myrect. MinX + 8 + stringwidth - XDPI . stringwidth, 

myrp.cp_y + fontheight); 
Text(&myrp, XDPI. string, XDPI . charcount) ; 

Move(&myrp, myrect. MinX + 8 + stringwidth - YDPI . stringwidth, 

myrp.cp_y + fontheight); 
Text(&myrp, YDPI. string, YDPI . charcount) ; 

Move(&myrp, myrect. MinX + 8 + stringwidth - entrynum. stringwidth, 

myrp.cp_y + fontheight); 
Text(&myrp, entrynum. string, ent rynum. char count ) ; 

myrect. MinX = myrect. MinX + cliprectside; 
myrect. MaxX - myrect. MaxX - cliprectside; 
myrect. MinY = myrect. MinY + (5 * fontheight) + 8; 
myrect. MaxY = myrect. MaxY - 8; 

SetAPen (&myrp, mydrawinf o->dri_Pens [SHINEPEN] ) ; /* Draw a box around */ 
Move(&myrp, myrect. MinX - 1, myrect. MaxY + 1) ; /* the cliprect. */ 
Draw(&myrp, myrect. MaxX + 1, myrect. MaxY + 1) 
Draw(&myrp, myrect. MaxX + 1, myrect. MinY - 1) 

SetAPen (&myrp, mydrawinf o->dri_Pens [SHADOWPEN] ) ; 
Draw(&myrp, myrect. MinX - 1, myrect. MinY - 1) ; 
Draw(&myrp, myrect. MinX - 1, myrect .MaxY) ; 

SetAPen (&myrp, mydrawinf o->dri_Pens [TEXTPEN] ) ; 

/* Fill up a buffer with a list of the available fonts */ 
afsize = AvailFonts ( (STRPTR) afh, OL, AFF_MEMORY | AFF_DISK| AFF_SCALED | AFF_TAGGED) ; 
do 

{ 

afh = (struct AvailFontsHeader *) AllocMem (afsize, 0) ; 
if (afh) 

{ 

afshortage = AvailFonts ( (STRPTR) afh, afsize, 

AFF_MEMORY | AFF_DISK | AFF_SCALED | AFF_TAGGED) ; 
if (afshortage) 
{ 



FreeMem (afh, afsize); 
afsize += af shortage; 

afh = (struct AvailFontsHeader *) (-1L); 
} 
} 
} while (afshortage && afh) ; 

if (afh) 

{ 

/* This is for the layers . library clipping region that gets attached to */ 
/* the window. This prevents the application from unnecessarily */ 
/* rendering beyond the bounds of the inner part of the window. For */ 
/* more information on clipping, see the Layers chapter of this manual. */ 

if (new_region = NewRegionO) /* More layers stuff */ 

{ 

if (OrRectRegion (new_region, &myrect) ) ; /* Even more layers stuff */ 

{ 

/* Obtain a pointer to the window's rastport and set up some of */ 
/* the rastport attributes. This example obtains the text pen */ 
/* for the window's screen using the GetScreenDrawInf o ( ) function. */ 
mycliprp = mywin->RPort ; 
SetAPen(mycliprp, mydrawinf o->dri_Pens [TEXTPEN] ) ; 

MainLoop ( ) ; 

} 

DisposeRegion (new_region) ; 

} 

FreeMem (afh, afsize); 

} 
} 

FreeScreenDrawInf o (mywin->WScreen, mydrawinf o) ; 

} 

CloseWindow (mywin) ; 

} 

CloseLibrary (UtilityBase) ; 

} 

CloseLibrary (LayersBase) ; 

} 

CloseLibrary (Gf xBase) ; 

} 

CloseLibrary (IntuitionBase) ; 

} 

CloseLibrary (Diskf ontBase) ; 

} 
} 

void MainLoop (void) 

{ 

UWORD x; 

struct Task *mytask; 

struct IntuiMessage *mymsg; 

BOOL aok = TRUE; 

struct TAvailFonts *afont; 

struct TextFont *myfont; 

UBYTE buf [8] ; 

ULONG dpi; 

mytask = FindTask (NULL) ; 

afont = (struct TAvailFonts *) & (afh [1] ) ; 

for (x = 0; (x < af h->af h_NumEntries) ; x++) 

{ 

if (aok) 

{ 

if (myfont = OpenDiskFont (& (af ont->taf_Attr) ) ) 

{ 
SetAPen(&myrp, mydrawinf o->dri_Pens [BACKGROUNDPEN] ) ; /*Print the TextFont attributes.*/ 
RectFill ( &myrp, stringwidth, mywin- >BorderTop + 4, 

mywin->Width - (mywin- >BorderRight + 1) , myrect.MinY - 2 ) ; 

SetAPen(&myrp, mydrawinf o->dri_Pens [TEXTPEN] ) ; 



Move ( &myrp, stringwidth + mywin->BorderLef t , 

mywin->BorderTop + 4 + (myrp. Font->tf_Baseline) ); 
Text ( &myrp, (UBYTE * ) myf ont->tf_Message .mn_Node . ln_Name , 

StrLen ( (UBYTE * ) myf ont->tf_Message .mn_Node . ln_Name) ) ; 

Move(&myrp, stringwidth + mywin->BorderLef t , myrp.cp_y + fontheight) ; /* Print the */ 
sprintf (buf, "%d\0", myf ont->tf_YSize) ; /* font's Y Size. */ 

Text(&myrp, buf , StrLen (buf )) ; 

Move(&myrp, stringwidth + mywin->BorderLef t , myrp.cp_y + fontheight); /*Print the X DPI */ 
dpi = GetTagData( TA_DeviceDPI , OL, 

((struct TextFontExtension *) (myf ont->tf_Extension) ) ->tfe_Tags) ; 
if (dpi) 

{ 

sprintf (buf, "%d\0", ((dpi & OxFFFFOOOO) >>16) ) ; 
Text(&myrp, buf, StrLen (buf )) ; 

} 

else Text(&myrp, "nil", 3L) ; 

Move(&myrp, stringwidth + mywin->BorderLef t , myrp.cp_y + fontheight); /* Print the Y DPI */ 
if (dpi) 

{ 

sprintf (buf, "%d\0", (dpi & OxOOOOFFFF) ) ; 
Text(&myrp, buf, StrLen (buf )) ; 

} 

else Text(&myrp, "nil", 3L) ; 

Move(&myrp, stringwidth + mywin->BorderLef t , myrp.cp_y + fontheight); /* Print the */ 
sprintf (buf, "%d\0", x) ; /* entrynum. */ 

Text(&myrp, buf, StrLen (buf )) ; 

SetFont (mycliprp, myfont) ; 
old_region = InstallClipRegion (mywin->WLayer , new_region) ; /*Install clipping rectangle*/ 

SetRast (mycliprp, mydrawinf o->dri_Pens [BACKGROUNDPEN] ) ; 

Move ( mycliprp, myrect.MinX, myrect.MaxY - (myf ont->tf_YSize - myf ont->tf_Baseline) ) ; 

Text (mycliprp, alphabetstring, alphabetcharcount) ; 

Delay (100) ; 

new_region = InstallClipRegion (mywin->WLayer, old_region) ; /*Remove clipping rectangle */ 

while (mymsg = (struct IntuiMessage *) GetMsg (mywin->UserPort) ) 

{ 

aok = FALSE; 

x = af h->af h_NumEntries; 
ReplyMsg ( (struct Message *)mymsg); 
} 

if (mytask->tc_SigRecvd & SIGBREAKF_CTRL_C) /* Did the user hit CTRL-C (the shell */ 
{ /* window has to receive the CTRL-C)? */ 

aok = FALSE; 

x = afh->afh_NumEntries; 

VPrintf ("Ctrl-C Break\n", NULL) ; 

} 

CloseFont (myfont) ; 

} 
} 

af ont++; 

} 
} 

ULONG StrLen (UBYTE *string) 

{ 

ULONG X = OL; 

while (string [x++] ) ; 
return ( --x) ; 
} 



How is an Amiga Font Structured in Memory? 

So far, this chapter has concentrated on using library functions to render text, letting the system worry about the 
layout of the underlying font data. As far as the OS representation of a loaded font is concerned, outline fonts and 
normal bitmap fonts are structured identically. Color fonts have some extras information associated with them 
and are discussed a little later. Every loaded font, including color fonts, has a TextFont structure associated with 
them: 



struct TextFont { 

struct Message tf_Message; 



/* reply message for font removal */ 



UWORD tf_YSize; 

UBYTE tf_Style; 

UBYTE tf_Flags; 

UWORD tf_XSize; 

UWORD tf_Baseline; 

UWORD tf BoldSmear; /* smear to affect a bold enhancement */ 



UWORD tf_Accessors; 

UBYTE tf_LoChar; 

UBYTE tf_HiChar; 

APTR tf CharData; 



/* the bit character data */ 



}; 



UWORD 
APTR 



APTR 
APTR 



tf_Modulo; /* the row modulo for the strike font data */ 
tf_CharLoc; /* ptr to location data for the strike font */ 
/* 2 words: bit offset then size */ 

tf_CharSpace; /* ptr to words of proportional spacing data */ 
tf_CharKern; /* ptr to words of kerning data */ 



The first field in this structure is a Message structure. The node in this Message structure is what the OS uses to 
link together the fonts in the system list. From this node, an application can extract a font's name. The other 
fields in the TextFont structure are as follows: 



tf YSize 



The maximum height of this font in pixels. 



tf_Style 



The style bits for this particular font, which are defined in <graphics/text.h>. These include the same 
style bits that were mentioned in the discussion of the TextAttr structure in the "Choosing the Font" 
section of this chapter. In addition to those bits, there is also the FSF_COLORFONT bit, which 
identifies this as a special kind of TextFont structure called a ColorTextFont structure. This is 
discussed later in this chapter. 
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tf_Flags 



The flags for this font, which were mentioned along with the style bits in the section, "Choosing the 
Font". 



tf_XSize 

If this font is monospaced (non-proportional), tf_XSize is the width of each character. The width 
includes the extra space needed to the left and right of the character to keep the characters from 
running together. 

tf Baseline 

The distance in pixels from the top line of the font to the baseline. 

tf_BoldSmear 

When algorithmically bolding, the Amiga currently "smears" a glyph by rendering it, moving over 
tf_BoldSmear number of pixels, and rerendering the glyph. 



tf_Accessors 

The number of currently open instances of this font (like the open count for libraries). 



tf_LoChar 

This is the first character glyph (the graphical symbol associated with this font) defined in this font. All 
characters that have ASCII values below this value do not have an associated glyph. 

tf_HiChar 

This is the last character glyph defined in this font. All characters that have ASCII values above this 
value do not have an associated glyph. An application can use these values to avoid rendering 
characters which have no associated glyphs. Any characters without an associated glyph will have the 
default glyph associated to them. Normally, the default glyph is a rectangle. 

tf_CharData 

This is the address of the bitmap from which the OS extracts the font's glyphs. The individual glyphs 
are bit-packed together. The individual bitmaps of the glyphs are placed in ASCII order side by side, 
left to right. The last glyph is the default glyph. The following is what the bitmap of the suits-8 font 
example looks like (suits8 is the complete, disk-based bitmap font example used later in this chapter): 



This font is rather sparse, as it only has five glyphs. Most fonts at least have glyphs for each letter of 
the alphabet. In this example, each glyph represents a symbol for a suit in a standard deck of cards 
(from left to right: hearts, spades, diamonds, and clubs). Notice that there is no space between the 
individual glyphs. The spacing information is kept in separate tables to reduce the amount of memory 
occupied by the font. 

tf_Modulo 

This is number of bytes the pointer must move to go from one line of a glyph to the next. This is the 
pixel width of the entire font bitmap divided by eight. Notice that the bitmap above does not stop 
after it gets to the end of the last glyph. It is padded with zero bits to the nearest WORD boundary. 
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tf_CharLoc 

This is a pointer to the CharLoc, the character location table. This table tells the OS how far into the 
bitmap to look for a character and how many pixels to fetch from each row. The CharLoc table for 
the suits-8 font looks like this: 

$000000 OB, $000B000B, $00160007, $001D000B, $0028000C 

Each of the five long words in this character location table corresponds to a glyph in Suits-8. Each long 
word is broken up into two word values. The first word is the offset in pixels from the left edge of the 
bitmap to the first column containing the corresponding glyph. The second word is the width in pixels of 
the corresponding glyph image in the bitmap (note, this is not the width of the actual glyph as the actual 
glyph will have some space on either side of it). For example, the diamond character (the third 
character) starts at offset $16 (22) and it is 7 pixels wide. 

tf_CharSpace 

This is a pointer to an array of WORDs containing the width of each glyph in the font. Each entry tells 
the OS how much to increment the current horizontal position (usually RastPort.cp_X). For reverse 
path fonts, these values can be negative. 

tf_CharKern 

This is a pointer to an array of "kerning" values. As it is used here, the term "kerning" is unorthodox. 
On the Amiga, kerning refers to the number pixels to leave blank before rendering a glyph. The 
normal typographical definition of the word refers to the number of pixels to back up before rendering 
the current glyph and is usually associated with a specific pair of glyphs rather than one particular 
glyph. 

For each glyph the system renders, it has to do several things: 

1 ) Get the value from the kerning table that corresponds to this glyph and begin the rendering that number 



of pixels to the right. 

2) Find this glyph's bitmap using the CharLoc table and blit the glyph to the rastport. 

3) If this is a proportional font, look in the spacing table and figure how many pixels to advance the 
rastport's horizontal position. For a monospaced font, the horizontal position advance comes from the 
TextFont's tf_XSize field. 

Under Release 2, when the system opens a new font, it creates an extension to the TextFont structure called the 
TextFontExtension. This extension is important because it contains a pointer to the font's tag list, which is 
where the system keeps the font's TADeviceDPI values. The TextFont's tf_Message.mn_ReplyPort field 
contains a pointer to the TextFontExtension structure (the <graphics/text.h> include file #defines 
tf_Message.mn_ReplyPort as tf_Extension). The only field of interest in the TextFontExtension structure is: 

struct Tagltem *tfe_Tags; /* Text Tags for the font */ 

which points to the font's tag list. Before accessing the tag list, an application should make sure that this font has 
a corresponding TextFontExtension. The ExtendFont() function will return a value of TRUE if this font already 
has an extension or ExtendFont() was able to create an extension for this font. 
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But What About Color Fonts? 

When the Amiga loads a color font, it has to account for more information than will fit into the TextFont structures. 
For color fonts, the Amiga uses a superset of the TextFont structure called the ColorTextFont structure (defined 
in <graphics/text.h>): 

struct ColorTextFont { 

struct TextFont ctf_TF; 

UWORD ctf_Flags; /* extended flags */ 

UBYTE ctf_Depth; /* number of bit planes */ 

UBYTE ctf_FgColor; /* color that is remapped to FgPen */ 

UBYTE ctf_Low; /* lowest color represented here */ 

UBYTE ctf_High; /* highest color represented here */ 

UBYTE ctf_PlanePick; /* PlanePick ala Images */ 

UBYTE ctf_PlaneOnOf f ; /* PlaneOnOff ala Images */ 

struct ColorFontColors *ctf_ColorFontColors; /* colors for font */ 

APTR ctf_CharData [8] ; /* pointers to bit planes ala tf_CharData */ 

}; 

The ctf_TF field is the TextFont structure described in the previous section. There are two minor differences 
between the data stored in a color font's TextFont structure and an ordinary TextFont structure. The first is that 
the color font's TextFont.tf_Style field has the FSF_COLORFONT bit set. The other difference is that the bitmap 
that TextFont.tf_CharData points to can be a multi-plane bitmap. 

The ctf_Flags field is a bitfield that supports the following flags: 

CT_COLORFONT The color map for this font contains colors specified by the designer. 

CT_GREYFONT The colors for this font describe evenly stepped gray shades from low to high. 

The ctf_Depth field contains the bitplane depth of this font's bitmap. 

The ctf_FgColor contains the color that will be dynamically remapped during output by changing ctf_FgColor to 
RastPort.FgPen. This field allows a ColorTextFont to contain color outlines, shadows, etc. while also containing 
a predominant color that can be changed by the user. If the font does not have a predominant color, ctf_FgColor 
is OxFF. For example, given a color font that has a blue and red outline and a white center, the person designing 
the font can set ctf_FgColor equal to white. Then when the font is used in a paint package that supports color 
fonts, the white will change to the current foreground color. 

The fields ctf_Low and ctf_High contain the lowest and highest color values in the ColorTextFont. For 
example, a four bitplane color font can have sixteen colors, but the font may use only nine of those colors, thus 



ctf_Low=0 and ctf_High=8. The most important use of these colors is for defining the boundaries of a gray scale 
font. If the font uses less than the total number of colors around but needs white as the lowest and black as the 
highest level of gray, the boundaries would have to be defined in order for the font to be rendered correctly. 
Defaults for these values should be the lowest and the highest values for the given number of bitplanes. 

The ctf_PlanePick and ctf_PlaneOnOff contain information for saving space in memory for some types of 
ColorTextFont structures. The ctf_PlanePick field contains information about where each plane of data will be 
rendered in a given bitmap. The ctf_PlaneOnOff field contains information about planes that are not used to 
render a plane of font data. If ctf_PlaneOnOff contains a zero bit for a given plane, that bitplane is cleared. If 
ctf_PlaneOnOff contains a set bit for a given plane, that bitplane is filled. For more information on how the 
ctf_PlaneOnOff and ctf_PlanePick fields work see the "Specifying the Colors of a Bob" section of the "Graphics 
Sprites, Bobs and Animation" chapter of this book. 
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The ctf_ColorFontColors field contains a pointer to a ColorFontColors structure: 

struct ColorFontColors { 

UWORD cf c_Reserved; /* *must* be zero */ 

UWORD cfc_Count; /* number of entries in cf c_ColorTable */ 

UWORD *cf c_ColorTable; /* 4 bit per component color map packed xRGB */ 

}; 

Which specifies the colors used by this font. The ColorFontColors cfc_Count field contains the number of 
colors defined in this structure. Each color is defined as a single, UWORD entry in the cfc_ColorTable. For each 
entry in cfc_ColorTable, the lowest four bits make up the blue element, the next four bits the green element, the 
next four bits the red element, and the upper four bits should be masked out. 

The ctf_CharData[] fields is an array of pointers to each of the bitplanes of the color font data. 

The Composition of a Bitmap Font on Disk 

For each Amiga bitmap font stored on disk (normally in the FONTS: assign directory), there is a corresponding 
".font" file, a directory, and within that directory, a series of files bearing numeric names. For example, for the font 
Sapphire, within FONTS:, there is a file called sapphire.font, a directory called Sapphire, and within the directory 
Sapphire are the files 14 and 19. 

For a bitmap font (including color fonts), the ".font" file is a FontContentsHeader structure: 

struct FontContentsHeader { 

UWORD fch_FileID; /* FCH_ID */ 

UWORD f ch_NumEntries; /* the number of FontContents elements */ 

struct FontContents fch_FC[]; /* or struct TFontContents fch_TFC[]; */ 

}; 

#define MAXFONTPATH 256 

Where the fch_FilelD field can be be either: 

FCHJD OxOfOO This FontContentsHeader uses FontContents structures to describe the 

available sizes of this font. 
TFCHJD 0x0f02 This FontContentsHeader uses TFontContents structures to describe the 

available sizes of this font. 

The fch_FilelD can also be equal to 0x0f03, but that is only for scalable outline fonts. 

The FontContents structure: 

struct FontContents { 

char f c_FileName [MAXFONTPATH] ; 
UWORD fc_YSize; 
UBYTE fc_Style; 
UBYTE fc_Flags; 



}; 

describes one of the sizes of this font that is available to the system as a designed font size. For each 
FontContents structure, there should be a corresponding font descriptor file in this font's directory that contains 
data for this size font. The FontContents fields correspond to the similarly named field in the TextFont structure. 
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The TFontContents structure is almost the same as the FontContents structure except that it allows the OS to 
store tag value pairs in the extra space not used by the file name. Currently, this allows the OS to preserve the X 
and Y DPI (TA_DeviceDPI) values for a font. 

struct TFontContents { 

char tfc_FileName [MAXFONTPATH-2] ; 

UWORD tfcJTagCount; /* including the TAG_DONE tag */ 

/* 

* if tfc_TagCount is non-zero, tfc_FileName is overlaid with 

* Text Tags starting at: (struct Tagltem *) 

* &tf c_FileName [MAXFONTPATH- (tf c_TagCount*sizeof 

* (struct Tagltem))] 



*/ 




UWORD 


tfc_YSize 


UBYTE 


tfc_Style 


UBYTE 


tfc Flags 



The fch_NumEntries contains the number of font sizes (and the number of FontContents or TFontContents 
structures) that this ".font" file describes. The fch_FC[] is the array of FontContents or TFontContents 
structures that describe this font. 

For each font size described in a FontContents (or TFontContents) structure, there is a corresponding file in 
that font's directory whose name is its size. For example, for the font size Sapphire-19, there is a file in the 
Sapphire directory called 19. That file is basically a DiskFontHeader disguised as a loadable DOS hunk and is 
known as a font descriptor file. This allows the diskfont.library to use the dos. library to load the module just like it 
was a hunk of relocatable 680x0 instructions. It even contains two instructions before the real DiskFontHeader 
structure that will cause the 680x0 to stop running the DiskFontHeader if it does inadvertently get executed. 

#define MAXFONTNAME 32 /* font name including ".font" */ 

struct DiskFontHeader { 

/* the following 8 bytes are not actually considered a part of */ 
/* the DiskFontHeader, but immediately precede it. The */ 
/* NextSegment is supplied by the linker/loader, and the */ 
/* ReturnCode is the code at the beginning of the font in case */ 
/* someone runs it . . . */ 

/* ULONG dfh_NextSegment; actually a BPTR */ 

/* ULONG dfh_ReturnCode; MOVEQ #0,D0 : RTS */ 

/* here then is the official start of the DiskFontHeader... */ 
struct Node dfh_DF; /* node to link disk fonts */ 

UWORD dfh_FileID; /* DFH_ID */ 

UWORD dfh_Revision; /* the font revision */ 

LONG dfh_Segment; /* the segment address when loaded */ 

char dfh_Name [MAXFONTNAME] ; /* the font name (null terminated) */ 
struct TextFont dfh_TF; /* loaded TextFont structure */ 

}; 

/* unfortunately, this needs to be explicitly typed */ 
/* used only if dfh_TF . tf_Style FSB_TAGGED bit is set */ 
#define dfh_TagList dfh_Segment /* destroyed during loading */ 

The dfh_DF field is an Exec Node structure that the diskfont library uses to link together the fonts it has loaded. 
The dfh_FilelD field contains the file type, which currently is DFH_ID (defined in <libraries/diskfont.h>). The 
dfh_Revision field contains a revision number for this font. The dfh_Segment field will contain the segment 
address when the font is loaded. The dfh_FontName field will contain the font's name after the font descriptor is 



LoadSeg()'ed. The last field, dfh_TextFont is a TextFont structure (or ColorTextFont structure) as described in 
the previous section. The following is a complete example of a proportional, bitmap font. 
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* A sparse (but complete) sample font. 

* 1. Assemble this file (assumed to have been saved as "suits8 .asm" ) . For 

* example, if you have the CAPE 680x0 assembler, and you have assigned 

* "include:" to the directory containing your include files, use: 

* CAsm -a "suits8.asm" -o "suits8.o" -i "include:" 

* Link "suits8.o". For example, if you have Lattice, use: 

* BLink from "suits8.o" to "suits8" 

* 2. Create the subdirectory "Fonts : suits" . Copy the file "suits8" 

* (created in step 1) to "Fonts : suits/8" . 
* 

* 3. Create a font contents file for the font. You can do this by two 

* methods : 

* a. Run the program "System/FixFonts" which will create the file 

* "Fonts : suits . font " automatically. 

* b. Use the NewFontContents ( ) call in the diskfont library to create a 

* FontContentsHeader structure, which can be saved in the Fonts: 

* directory as "suits . font " . This is essentially what FixFonts does. 
* 

* The next word contains the font YSize; in this case, 0x0008. 

* The next byte contains the font Flags, in this case 0x00. 

* The last byte contains the font characteristics, in this case 0x60. This 

* says it is a disk-based font (bit 1 set) and the font has been removed 

* (bit 7 set) , saying that the font is not currently resident. 

* Summary of suits. font file: 

* Name: fch_FileID f ch_NumEntries fc_FileName fc_YSize fc_Flags fc_Style 

* Size: word word MAXFONTPATH bytes word byte byte 

* Hex: OfOO 0001 73756974732F3800 0008 00 60 

* ASCII: suits/8 \0 

* The correct length of a font file may be calculated with this formula: 

* length = ((number of font contents entries) * (MAXFONTPATH+4) ) + 4 . In 

* this case (one entry), this becomes (MAXFONTPATH + 8) or 264. 

* To try out this example font, do the following. Use the Fonts 

* Preferences editor or a program that allows the user to select fonts. 

* Choose the "suits" font in size 8. This example font defines ASCII 

* characters 'a' 'b' ' c' and 'd' only. All other characters map to a 

* rectangle, meaning "character unknown". 

INCLUDE "exec/types . i" 
INCLUDE "exec/nodes . i" 
INCLUDE "libraries/diskfont .i" 

MOVEQ #-l,D0 ; Provide an easy exit in case this file is 
RTS ; "Run" instead of merely loaded. 



DC.L 

DC.L 

DC . B NT_F0NT 

DC.B 

DC.L fontName 

DC.W DFH_ID 

DC.W 1 

DC.L 



ln_Succ 

ln_Pred 

ln_Type 

ln_Pri 

ln_Name 

FilelD 

Revision 

Segment 



These five entries comprise a Node 
structure, used by the system to link 
disk fonts into a list. See the 
definition of the "DiskFontHeader" 
structure in the "libraries/diskf ont . i 1 ' 
includefile for more information. 



* The next MAXFONTNAME bytes are a placeholder. The name of the font 

* contents file (e.g. "suits . font " ) will be copied here after this font 

* descriptor is LoadSeg-ed into memory. The Name field could have been 



* left blank, but inserting the font name and size (or style) allows one to 

* tell something about the font by using "Type OPT H" on the file. 

font Name : 

DC.B "suits8" ; Name 

* If your assembler needs an absolute value in place of the "length" 

* variable, simply count the number of characters in Name and use that. 



length 



EQU 
DCB.B 



*-f ontName 
MAXFONTNAME-length, 



Assembler calculates Name's 
Padding of null characters. 



length. 



font: 

DC.L 
DC.L 
DC.B 
DC.B 
DC.L 
DC.L 
DC.W 
DC.W 
DC.B 
DC.B 
DC.W 
DC.W 
DC.W 
DC.W 
DC.B 
DC.B 
DC.L 
DC.W 



DC.L 
DC.L 
DC.L 







NT_FONT 



f ontName 





8 



FPF_DESIGNED 

14 

6 

1 



97 

100 

f ontData 



f ontLoc 
f ontSpace 
f ontKern 



ln_Succ 
ln_Pred 
ln_Type 
ln_Pri 
ln_Name 
mn_ReplyPort 

(Reserved for 1.4 system use.) 
tf_YSize 
tf_Style 
! FPF_PROPORTIONAL ! FPF_DISKFONT 
tf XSize 



The rest of the information is a 
TextFont structure. See the 
"graphics/text . i" include file for 
more information. 



tf_Flags 



tf_Baseline 

tf_BoldSmear 

tf_Accessors 

tf_LoChar 

tf_HiChar 

tf_CharData 

tf Modulo < 



tf_Baseline must be no greater 
than tf_YSize-l, otherwise 
algorithmically-generated styles 
(italic in particular) can 
corrupt system memory. 



* add this to the data pointer to go 

* from one row of a character to the 

* next row of it. 

tf_CharLoc < * bit position in the font data 

tf_CharSpace * at which the character begins, 
tf CharKern 



The four characters of this font define the four playing-card suit 
symbols. The heart, club, diamond, and spade map to the lower-case ASCII 
characters 'a', 'b', 'C, and 'd' respectively The fifth entry in the 
table is the character to be output when there is no entry defined in the 
character set for the requested ASCII value. Font data is bit-packed 
edge to edge to save space. 



f ontData : 
DC.W 
DC.W 
DC.W 
DC.W 
DC.W 
DC.W 
DC.W 
DC.W 
DC.W 



$071C0, 
$0FBE3, 
$07FCF, 
$03F9F, 
$01F0E, 
$00E00, 
$00403, 
$00000, 
$00000, 



$08040, 
$0E0E0, 
$0F9F3, 
$0FFFF, 
$0B9F3, 
$080E0, 
$0E040, 
$00000, 
$00000, 



$070FF, $ 
$0F8C0, $ 
$026C0, $ 
$0FFC0,$ 
$026C0, $ 
$020C0, $ 
$0F8FF, $ 
$00000, $ 
$00000, $ 



0F000 
03000 
03000 
03000 
03000 
03000 
OFOOO 
00000 
00000 



97 (a) 



98 (b) 
X 



99 (c) 
X X 



100 (d) 



f ontLoc : 
DC.L 
DC.L 
DC.L 
DC.L 
DC.L 



$00000000B 
$0000B000B 
$000160007 
$0001D000B 
$00028000C 



The fontLoc information is used to "unpack" the 
f ontData. Each pair of words specifies how the 
characters are bit-packed. For example, the first 
character starts at bit position 0x0000, and is 
OxOOOB (11) bits wide. The second character starts 
at bit position OxOOOB and is OxOOOB bits wide, and 
so on. This tellsthe font handler how to unpack 
the bits from the array. 



f ontSpace : 

DC.W 000012,000012 

DC.W 000008,000012,000013 



f ontSpace array: Use a space this wide 
to contain this character when it is 
printed. For reverse-path fonts these 
values would be small or negative. 



f ontKern: 

DC.W 000001,000001 

DC.W 000001,000001,000001 



f ontKern array: Place a space this wide 
after the corresponding character to 
separate it from the following character. 
For reverse-path fonts these values would 
be large negative numbers, approximately 



fontEnd: 
END 



the width of the characters . 
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Function Reference 



The following are brief descriptions of the Graphics and Diskfont library functions that deal with text. See the 
Amiga ROM Kernel Reference Manual: Includes and Autodocs for details on each function call. 

Table 29-1 : Graphics Library Text Functions 



Function Description 

Text() Render a text string to a RastPort. 

SetFont() Set a RastPort's font. 

AskFont() Get the TextAttr for a RastPort's font. 

OpenFont() Open a font currently in the system font list. 

CloseFont() Close a font. 

AddFont() Add a font to the system list. 

RemFont() Remove a font from the system list. 

StripFont() Remove the tf_Extension from a font (V36). 

WeighTAMatchQGet a measure of how well two fonts match (V36). 



ClearScreen() Clear RastPort from the current position to the end of the RastPort. 

ClearEOL() Clear RastPort from the current position to the end of the line. 

AskSoftStyle() Get the soft style bits of a RastPort's font. 

SetSoftStyle() Set the soft style bits of a RastPort's font. 

TextLength() Determine the horizontal raster length of a text string using the current 

RastPort settings. 
TextExtent() Determine the raster extent (along the X and Y axes) of a text string 

using the current RastPort settings (V36). 
FontExtent() Fill in a TextExtent structure with the bounding box for the characters in 

the specified font (V36). 
TextFit() Count the number of characters in a given string that will fit into a given 

bounds, using the current RastPort settings (V36). 



Table 29-2: Diskfont Library Text Functions 



Function 

Avaiir-ontso 

NewFontContents() 

DisposeFontContents() 

NewScaledDiskFont() 

OpenDiskFontQ 



Description 

inquire wnicn tonts are avanaoie from oisk ana/or memory. 
Create a FontContents image for a font. 
Free the result from NewFontContents(). 
Create a DiskFont scaled from another font (V36). 
Open a font, loading it from disk if necessary. 
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Chapter 30 
Layers Library 



This chapter describes the layers library which provides routines that are used to manage overlapping rectangular 
drawing areas that share a common display. Intuition uses the layers library to manage its system of windows. 

The chapter also describes the use of regions, special structures used to mask off areas where drawing can take 
place. Regions are installed through the layers library function lnstallClipRegion() but the routines for the 
creation, disposal and manipulation of regions are part of the graphics library. 



Layers 



The concept of a layer is closely tied to Intuition windows. A layer is a rectangular drawing area. A layer can 
overlap other layers and has a display priority that determines whether it will appear in front or behind other 
layers. Every Intuition window has an associated Layer structure. Layers allow Intuition and application programs 
to : 

Share a display's BitMap among various tasks in an orderly way by creating layers, separate drawing 
rectangles, within the BitMap. 

Move, size or depth-arrange a layer while automatically keeping track of which portions of other layers 
are hidden or revealed by the operation. 

Manage the remapping of coordinates, so the application need not track the layer's offset into the 
BitMap. 

Maintain each layer as a separate entity, which may optionally have its own BitMap. 

Automatically update same newly visible portions. 

The layers library takes care of housekeeping: the low level, repetitive tasks which are required to keep track of 
where to place bits. The layers library also provides a locking mechanism which coordinates display updating 
when multiple tasks are drawing graphics to layers. The windowing environment provided by the Intuition library 
is largely based on layers. 
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WARNING: Layers may not be created or used directly with Intuition screens. Intuition 
windows are the only supported method of adding layers to Intuition screens. Only the layer 
locking and unlocking functions are safe to use with Intuition. An application must create and 
manage its own View if it will be creating layers directly on the display. 

The Layer Structure 

The internal representation of layers is essentially a set of clipping rectangles. Each layer is represented by an 
instance of the Layer structure. All the layers in a display are linked together through the Layerjnfo structure. 
Any display shared by multiple layers (such as an Intuition screen) requires one Layerjnfo data structure to 
handle interactions between the various layers. Here is a partial listing of the Layer structure from 
<graphics/clip.h>. (For a complete listing refer to the Amiga ROM Kernel Reference Manual: Includes and 
Autodocs.) 

struct Layer 

{ 

struct Layer *f ront , *back; 

struct ClipRect *ClipRect; /* read ROMs to find 1st cliprect */ 

struct RastPort *rp; struct Rectangle bounds; 



}; 



UWORD Flags; /* obscured ?, Virtual BitMap? */ 

struct BitMap *SuperBitMap; 



struct Region *DamageList; /* list of rectangles to refresh */ 

/* through */ 



The Layer Structure is Read-Only. Applications should never directly modify any of the 
elements of the Layer structure. In addition, applications should only read the front, back, rp, 
bounds, Flags, SuperBitMap and DamageList elements of the Layer structure. (Some of 
these elements are subject to dynamic change by the system so proper layer locking 
procedures must be followed when relying on what the application has read.) 

The Layer's RastPort 

When a layer is created, a RastPort is automatically to go along with it. The pointer to the RastPort is contained 
in the layer data structure. Using this RastPort, the application may draw anywhere into the layer's bounds 
rectangle. If the application tries to draw outside of this rectangle, the graphics routines will clip the graphics. 

Here is sample code showing how to access the layer's RastPort: 

struct RastPort *myRPort ; /* allocate a RastPort pointer for each layer */ 
myRPort = layer- >rp; 

/* The layer's RastPort may be used with any of the graphics library 

** calls that require this structure. For instance, to fill layer 

** with color: 

*/ 

SetRast (layer- >rp, color); 

/* set up for writing text into layer */ 
SetDrMd ( layer- >rp, JAM1) ; 
SetAPen (layer- >rp, 0) ; 
Move (layer- >rp, 5, 7); 

/* write into layer */ 
Text (layer- >rp, string, strlen (string) ) ; 
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Types of Layers 

The layers library supports three types of layers: simple refresh, smart refresh and super bitmap. The type of the 
layer, specified by the Flags field in the Layers structure, determines what facilities the layer provides. 

Use Only One Layer Type Flag The three layer-type Flags are mutually exclusive. That is, 
only one layer-type flag (LAYERSIMPLE, LAYERSMART and LAYERSUPER) should be 
specified. 

Simple Refresh Layer 

When an application draws into the layer, any portion of the layer that is visible (not obscured) will be rendered 
into the common BitMap of the viewing area. All graphics rendering routines are "clipped", so that only exposed 
sections of the layer are drawn into. No back-up of obscured areas is provided. 

If another layer operation is performed that causes an obscured part of a simple refresh layer to be exposed, the 
application must determine if the section need be refreshed, re-drawing the newly exposed part of the layer as 
required. 

The basic advantage of simple refresh is that it does not require back-up area to save drawing sections that 
cannot be seen, saving memory. However, the application needs to monitor the layer to see if it needs refreshing. 
This is typically performed with statements like: 



if ( layer- >Flags & LAYERREFRESH) 
refresh (layer) ; 

Smart Refresh Layer 

Under smart refresh, the system provides dynamic backup of obscured sections of the layer. The graphics 
routines will automatically draw into these backup areas when they encounter an obscured part of the layer. The 
backup memory will be used to automatically update the display when obscured sections later become exposed. 

With smart refresh layers, the system handles all of the refresh requirements of the layer, except when the layer is 
made larger. When parts of the layer are exposed by a sizing operation, the application must refresh the newly 
exposed areas. 

The advantage of smart refresh is the speed of updating exposed regions of the layer and the ability of the system 
to manage part of the updating process for the application.. Its main disadvantage is the additional memory 
required to handle this automatic refresh. 
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Super Bitmap Layer 

A super bitmap layer is similar to a smart refresh layer. It too has a back-up area for rendering graphics for 
currently obscured parts of the display. Whenever an obscured area is made visible, the corresponding part of 
the backup area is copied to the display automatically. 

However, it differs from smart refresh in that: 

The back-up BitMap is user-supplied, rather than being allocated dynamically by the system. 

The back-up BitMap may be as large or larger than the the current size of the layer. It may also be 
larger than the maximum size of the layer. 

To see a larger portion of a super bitmap on-display, use SizeLayerQ. To see a different portion of the super 
bitmap in the layer, use ScrollLayer(). 

When the graphics routines perform drawing commands, part of the drawing appears in the common BitMap (the 
on-display portion). Any drawing outside the displayed portion itself is rendered into the super bitmap. When the 
layer is scrolled or sized, the layer contents are copied into the super bitmap, the scroll or size positioning is 
modified, and the appropriate portions are then copied back into the layer. (Refer to the graphics library functions 
SyncSBitMap() and CopySBitMap(). 

Backdrop Layer 

A layer of any type may be designated a backdrop layer which will always appear behind all other layers. They 
may not be moved, sized, or depth-arranged. Non-backdrop layers will always remain in front of backdrop layers 
regardless of how the non-backdrop layer is moved, sized or depth-arranged. 

Opening the Layers Library 

Like all libraries, the layers library must be opened before it may be used. Check the Layers Autodocs to 
determine what version of the library is required for any particular Layers function. 

struct Library *LayersBase; 

if (NULL != (LayersBase = OpenLibrary ( "layers . library" , 33L) ) ) 

{ 

/* use Layers library */ 

CloseLibrary ( (struct Library *) LayersBase) ; 
} 
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Working with Existing Layers 

A common operation performed by applications is to render text or graphics into an existing layer such as an 
Intuition window. To prevent Intuition from changing the layer (for instance when the user resizes or moves the 
window) during a series of graphic operations, the layers library provides locking functions for obtaining exclusive 
access to a layer. 

These locking functions are also useful for applications that create their own layers if the application has more 
than one task operating on the layers asynchronously. These calls coordinate multiple access to layers. 

Table 30-1 : Functions for Intertask Control of Layers (Layers Library) 

LockLayer ( ) Lock out rendering in a single layer. 

UnlockLayer ( ) Release LockLayer ( ) lock. 

LockLayers ( ) Lock out rendering in all layers of a display. 

UnlockLayers ( ) Release LockLayers ( ) lock. 

LockLayerlnf o ( ) Gain exclusive access to the display's layers. 

UnlockLayerlnf o ( ) Release LockLayerlnf o ( ) lock. 

The following routines from the graphics library also allow multitasking access to layer structures: 

Table 30-2: Functions for Intertask Control of Layers (Graphics Library) 

LockLayerRom ( ) Same as LockLayer () , from layers library. 

UnlockLayerRom ( ) Release LockLayerRom ( ) lock. 

AttemptLockLayerRom( ) Lock layer only if it is immediately available. 

These functions are similar to the layers LockLayer() and UnlockLayer() functions, but do not require the layers 
library to be open. See the Amiga ROM Kernel Reference Manual: Includes and Autodocs for details. 

Intertask Operations 

If multiple tasks are manipulating layers on the same display they will be sharing a Layerjnfo structure and their 
use of it and its related data structures need to be coordinated. To ensure that a structure remains cohesive, it 
should be operated on by only one task at a time. The Layerjnfo encompasses all the layers existing on a 
single display. 

LockLayerlnfo() must be called whenever the visible portions of layers may be affected, or when the Layerjnfo 
structure is changed. 

void LockLayerlnf o ( struct Layer_Info *li ); 

The lock should be obtained whenever a layer is created, deleted sized or moved, as the list of layers that is being 
managed by the Layerjnfo data structure must be updated. 

It is not necessary to lock the Layerjnfo data structure while rendering, or when calling routines like 
ScrollLayer(), because layer sizes and on-display positions are not being affected. 
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Use UnlockLayerlnfo() when you have finished the layer operation: 

void UnlockLayerlnf o ( struct Layer_Info *li ); 

If you don't unlock the Layerjnfo then any other task calling LockLayerlnfo() on the same Layerjnfo structure 
will be blocked creating a potential deadlock situation. 

In addition to locking the Layerjnfo structure, the layer itself should be locked if it is shared between tasks so 
that only one task at a time renders graphics to it. LockLayerQ is used to get exclusive graphics output to a 
layer. 

void LockLayer ( long dummy, struct Layer *layer ) ; 

If a graphics function is in process, the lock will return when the function is completed. Other tasks are blocked 



only if they attempt to draw graphics into this layer, or try to obtain a lock on this layer. The MoveLayer(), 
SizeLayer() and ScrollLayer() functions automatically lock and unlock the layer they operate on. 

UnlockLayer() should be used after the graphics operation to make the layer available to other tasks again. 

void UnlockLayer ( struct Layer *layer ); 

If more than one layer must be locked, then the LockLayer() calls should be surrounded by LockLayerlnfo() and 
UnlockLayerlnfo() calls, to prevent deadlock situations. 

The layers library provides two additional functions, LockLayersQ and UnlockLayersQ, for locking multiple 
layers. 

void LockLayers ( struct Layer_Info *li ) ; 
void UnlockLayers ( struct Layer_Info *li ) ; 

LockLayersQ is used to lock all layers in a single command. UnlockLayersQ releases the layers lock. The 
system calls these routines during the BehindLayerQ, UpfrontLayerQ and MoveLayerlnFrontOf() operations 
(described below). 

Determing Layer Position 

If the viewing area has been separated into several layers, the application may need to find out which layer is 
topmost at a particular x,y coordinate. Use the WhichLayer() function for this: 

struct Layer *WhichLayer ( struct Layer_Info *li, long x, long y ) ; 

To be sure that no task adds, deletes, or changes the sequence of layers before this information is used, call 
LockLayerlnfo() before calling WhichLayer(), and call UnlockLayerlnfoQ when the operation is complete. In 
this way, the program may ensure that it is acting on valid information. Always check for a NULL return value 
(coordinate not in a layer) from Which Layer(). 
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Creating and Using New Layers 

The functions described in this section are generally not safe to use with Intuition. To create new layers for 
Intuition you use Intuition window calls (see the "Intuition Windows" chapter earlier in this book). 

Only applications that create and mange their own View will be able to call the layer creation and updating 
functions discussed here. 

Table 30-3: Functions for Creating and Updating Layers 



NewLayerlnfo() 
DisposeLayerlnfo() 


Allocating a Layerjnfo structure. 
Deallocating a Layerjnfo structure. 


CreateUpfrontLayer() 
CreateBehi nd Layer() 
DeleteLayer() 


Make a new layer in front of others. 
Make a new layer behind others. 
Remove and delete an existing layer. 


MoveLayer() 
SizeLayer() 
Scroll Layer() 


Change the position (not depth) of a layer. 

Change the size of a layer. 

Change the internal coordinates of a layer. 


BehindLayer() 
UpfrontLayer() 
MoveLayerlnFrontOf() 


Depth arrange a layer behind others. 
Depth arrange a layer in front of others. 
Depth arrange a layer to a specific position. 


SwapBitsKastPortClipHectQ 


hast,non-iayered ana non-damaging ciispiayoperation. 


BeginUpdateQ 
EndUpdateQ 


Synchronize optimized refreshing tor layer. 
End optimized layer refresh. 



Creating a Viewing Workspace 

A viewing workspace may be created by using the primitives InitVPortQ, InitViewQ, MakeVPort(), MrgCop(), 

and LoadView(). Please reference the "Graphics Primitives" chapter for details on creating a low-level graphics 
display. Do not create Layers directly on Intuition screens. Windows are the only supported method of creating a 



layer on a screen. 

Creating the Layers 

The application must first allocate and initialize a Layerjnfo data structure which the system uses to keep track 
of layers that are created, use statements like: 

struct Layer_Info *theLayerInf o; 

if (NULL != (theLayerlnf o = NewLayerlnf o ( ) ) ) 

{ 

/* use Layer_Info */ 

DisposeLayerlnf o (theLayerlnf o) ; 

} 
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Layers may be created in the common bit map by calling CreateUpfrontLayer() or CreateBehindLayerQ, with a 
sequence such as the following: 

struct Layer *layer; 
struct Layer_Info *theLayerInf ob- 
struct BitMap *theBitMap; 

/* requests construction of a smart refresh layer. */ 
if (NULL == (layer = CreateUpf rontLayer (theLayerlnf o, theBitMap, 
20, 20, 100, 80, LAYERSMART , NULL))) 
error ( "CreateUpf rontLayer ( ) failed.") ; 
else 

{ 

; /* layer successfully created here. */ 

} 
Allocating and Deallocating Layerjnfo 
Use NewLayerlnfo() to allocate and initialize a Layerjnfo structure and associated sub-structures. 

struct Layer_Inf o *NewLayerInf o ( void ) ; 

You must call this function before attempting to use any of the other layers functions described below. When you 
have finished with a Layerjnfo structure, use DisposeLayerlnfo() to deallocate it. 

void DisposeLayerlnf o ( struct Layer_Info *li ); 

This function deallocates a Layerjnfo and associated structures previously allocated with NewLayerlnfo(). 

Allocating and Deallocating Layers 

Layers are created using the routines CreateUpfrontLayer() and CreateBehindLayerQ. CreateUpfrontLayer() 
creates a layer that will appear in front of any existing layers. 

struct Layer *CreateUpf rontLayer ( struct Layer_Info *li, 

struct BitMap *bm, long xO , long yO , long xl , long yl, 
long flags, struct BitMap *bm2 ) ; 

CreateBehindLayer() creates a layer that appears behind existing layers, but in front of backdrop layers. 

struct Layer *CreateBehindLayer ( struct Layer_Info *li, 

struct BitMap *bm, long xO , long yO , long xl , long yl, 
long flags, struct BitMap *bm2 ) ; 

Both of these routines return a pointer to a Layer data structure (as defined in the include file 
<graphics/layers.h>), or NULL if the operation was unsuccessful. 

A New Layer Also Gets a RastPort. When a layer is created, the routine automatically creates 



a RastPort to go along with it. If the layer's RastPort is passed to the drawing routines, 
drawing will be restricted to the layer. See "The Layer's RastPort" section above. 

Use the DeleteLayer() call to remove a layer: 

LONG DeleteLayer ( long dummy, struct Layer *layer ) ; 

DeleteLayer() removes a layer from the layer list and frees the memory allocated by the layer creation calls listed 
above. 
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Moving and Sizing Layers 

The layers library includes three functions for moving and sizing layers: 

LONG MoveLayer ( long dummy, struct Layer *layer, long dx, long dy ) ; 
LONG SizeLayer( long dummy, struct Layer *layer, long dx, long dy ) ; 
LONG MoveSizeLayer ( struct Layer *layer, long dx, long dy, long dw, long dh) ; 

MoveLayer() moves a layer to a new position relative to its current position. SizeLayerQ changes the size of a 
layer by modifying the coordinates of the lower right corner of the layer. MoveSizeLayer() changes both the size 
and position of a layer in a single call. 

Changing a Viewport 

The ScrollLayer() function changes the portion of a super bitmap that is shown by a layer: 

void ScrollLayer( long dummy, struct Layer *layer, long dx, long dy ) ; 

This function is most useful with super bitmap layers but can also simulate the effect on other layer types by 
adding the scroll offset to all future rendering. 

Reordering Layers 

The layers library provides three function calls for reordering layers: 

LONG BehindLayer ( long dummy, struct Layer *layer ) ; 
LONG Upf rontLayer ( long dummy, struct Layer *layer ) ; 
LONG MoveLayerlnFrontOf ( struct Layer *layer_to_move, struct Layer *other_layer ) ; 

BehindLayerQ moves a layer behind all other layers. This function considers any backdrop layers, moving a 
current layer behind all others except backdrop layers. UpfrontLayer() moves a layer in front of all other layers. 
MoveLayerlnFrontOf() is used to place a layer at a specific depth, just in front of a given layer. 

As areas of simple refresh layers become exposed, due to layer movement or sizing for example, the newly 
exposed areas have not been drawn into, and need refreshing. The system keeps track of these areas by using a 
DamageList. To update only those areas that need it, the BeginUpdateQ EndUpdate() functions are called. 

LONG BeginUpdate ( struct Layer *1 ); 

void EndUpdate ( struct Layer *layer, unsigned long flag ) ; 

BeginUpdate() saves the pointer to the current clipping rectangles and installs a pointer to a set of ClipRects 
generated from the DamageList in the layer structure. To repair the layer, use the graphics rendering routines as 
if to redraw the entire layer, and the routines will automatically use the new clipping rectangle list. So, only the 
damaged areas are actually rendered into, saving time. 

Never Modify the DamageList. The system generates and maintains the DamageList region. 
All application clipping should be done through the lnstallClipRegion() function. 

To complete the update process call EndUpdatef) which will restore the original ClipRect list. 
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Sub-Layer Rectangle Operators 

The SwapBitsRastPortClipRect() routine is for applications that do not want to worry about clipping rectangles. 

void SwapBitsRastPortClipRect ( struct RastPort *rp, struct ClipRect *cr ); 

For instance, you may use The SwapBitsRastPortClipRect() to produce a menu without using Intuition. There 
are two ways to produce such a menu: 

1 . Create an up-front layer with CreateUpfrontLayer(), then render the menu in it. This could use lots of 
memory and require a lot of (very temporary) "slice-and-dice" operations to create all of the clipping 
rectangles for the existing windows and so on. 

2. Use SwapBitsRastPortClipRect(), directly on the display drawing area: 

Render the menu in a back-up area off the display, then lock all of the on-display layers so that 
no task may use graphics routines to draw over the menu area on the display. 

Next, swap the on-display bits with the off-display bits, making the menu appear. 

When finished with the menu, swap again and unlock the layers. 

The second method is faster and leaves the clipping rectangles and most of the rest of the window data 
structures untouched. 

Warning: All of the layers must be locked while the menu is visible if you use the second 
method above. Any task that is using any of the layers for graphics output will be halted while 
the menu operations are taking place. If, on the other hand, the menu is rendered as a layer, 
no task need be halted while the menu is up because the lower layers need not be locked. 

Layers Example 

For the sake of brevity, the example is a single task. No Layer locking is done. Also not the routine 
my Label Layer() is used to redraw the given layer. It is called only when a layer needs refreshing 

/* For the sake of brevity, the example is a single task. No Layer 

** locking is done. Also note that the routine myLabel Layer ( ) is used 

** to redraw a given layer. It is called only when a layer needs 

** refreshing. 

** Layers. c 

** SAS/C 5.10a 

** lc -bl -cfist -v -y layers 

** blink FROM LIBrc.o layers. o TO layers LIB LIB :1c. lib LIB : amiga . lib 

*/ 

/* Force use of new variable names to help prevent errors */ 
#define INTuT_V3 6_NAMES_ONLY 

#include <exec/types .h> 
#include <graphics/gfxbase . h> 
#include <graphics/layers . h> 
#include <graphics/displayinf o.h> 

#include <clib/exec_protos . h> 
#include <clib/dos_protos . h> 
#include <clib/graphics_protos . h> 
#include <clib/layers_protos . h> 

#include <stdio.h> 
#include <stdlib.h> 
#include <string.h> 

#ifdef LATTICE 

int CXBRK(void) { return(O); } /* Disable Lattice CTRL/C handling */ 

int chkabort (void) { return(O); } /* really */ 

#endif 



#define L_DELAY (100) 
#define S_DELAY (50) 

#define DUMMY (0L) 

#define RED_PEN (1) 
#define GREEN_PEN (2) 
#define BLUE_PEN (3) 

#define SCREENJD (2) 
#define SCREEN_W (320) 
#define SCREEN_H (200) 

/* the starting size of example layers, offsets are used for placement */ 

#define W_H (50) 

#define W_T (5) 

#define W_B ( (W_T+W_H) -1) 

#define W_W (80) 

#define W_L ( (SCREEN_W/2) - (W_W/2)) 

#define W_R ( (W_L+W_W) -1) 

/* size of the superbitmap */ 
#define SUPER_H SCREEN_H 
#define SUPER_W SCREEN_W 

/* starting size of the message layer */ 

#define M_H (10) 

#define M_T (SCREEN_H-M_H) 

#define M_B ( (M_T+M_H) -1) 

#define M_W (SCREEN_W) 

#define M_L (0) 

#define M_R ( (M_L+M_W) -1) 

struct Gf xBase *Gf xBase; 
struct Library *LayersBase; 

/* global constant data for initializing the layers */ 

LONG theLayerFlags [3] = { LAYERSUPER, LAYERSMART, LAYERSIMPLE }; 

UWORD colortable[] ■ { 0x000, 0xf44, 0x4f4, 0x44f }; 

/* 

** Clear the layer then draw in a text string. 

*/ 

VOID myLabelLayer (struct Layer *layer, LONG color, UBYTE *string) 

{ 

/* fill layer with color */ 
SetRast (layer->rp, color); 

/* set up for writing text into layer */ 
SetDrMd(layer->rp, JAM1) ; 
SetAPen ( layer- >rp, 0) ; 
Move (layer- >rp, 5, 7); 

/* write into layer */ 

Text (layer->rp, string, strlen (string) ) ; 

} 

/* 

** write a message into a layer with a delay. 

*/ 

VOID pMessage (struct Layer *layer, UBYTE *string) 

{ 

Delay (SJDELAY) ; 

myLabelLayer (layer, GREEN_PEN, string); 

} 

/* 

** write an error message into a layer with a delay. 

*/ 

VOID error (struct Layer *layer, UBYTE *string) 

{ 



myLabelLayer (layer , RED_PEN, string); 

Delay (LJDELAY) ; 

} 

/* 

** do some layers manipulations to demonstrate their abilities. 

*/ 

VOID doLayers (struct Layer *msgLayer, struct Layer *layer_array [] ) 

{ 

WORD ktr; 
WORD ktr_2; 

pMessage (msgLayer , "Label all Layers"); 

myLabelLayer (layer_array [0] , RED_PEN, "Super"); 

myLabelLayer (layer_array [1] , GREEN_PEN, "Smart"); 

myLabelLayer (layer_array [2] , BLUE_PEN, "Simple"); 

pMessage (msgLayer , "MoveLayer 1 InFrontOf 0"); 
if ( ! MoveLayer InFrontOf (layer_array [1] , layer_array [0] ) ) 
error (msgLayer , "MoveLayerlnFrontOf ( ) failed."); 

pMessage (msgLayer , "MoveLayer 2 InFrontOf 1"); 
if ( ! MoveLayerlnFrontOf (layer_array [2] , layer_array [1] ) ) 
error (msgLayer , "MoveLayerlnFrontOf ( ) failed."); 

pMessage (msgLayer, "Refresh Simple Refresh Layer"); 
myLabelLayer (layer_array [2] , BLUE_PEN, "Simple"); 

pMessage (msgLayer, "Incrementally MoveLayers . . . " ) ; 
for (ktr = 0; ktr < 30; ktr++) 

{ 

if (! MoveLayer (DUMMY, layer_array [1] , -1, 0)) 

error (msgLayer , "MoveLayerO failed."); 
if ( IMoveLayer (DUMMY, layer_array [2] , -2, 0)) 

error (msgLayer , "MoveLayerO failed."); 
} 

pMessage (msgLayer, "Refresh Simple Refresh Layer"); 
myLabelLayer (layer_array [2] , BLUE_PEN, "Simple"); 

pMessage (msgLayer , "make Layer the Upf rontLayer" ) ; 
if (! Upf rontLayer (DUMMY, layer_array [0] ) ) 

error (msgLayer , "Upf rontLayer ( ) failed."); 

pMessage (msgLayer , "make Layer 2 the BehindLayer" ) ; 
if (! BehindLayer (DUMMY, layer_array [2] ) ) 

error (msgLayer , "BehindLayer ( ) failed."); 

pMessage (msgLayer , "Incrementally MoveLayers again..."); 
for (ktr = 0; ktr < 30; ktr++) 

{ 

if ( IMoveLayer (DUMMY, layer_array [1] , 0, 1)) 

error (msgLayer , "MoveLayerO failed."); 
if ( IMoveLayer (DUMMY, layer_array [2] , 0, 2)) 

error (msgLayer , "MoveLayerO failed."); 



pMessage (msgLayer , "Refresh Simple Refresh Layer"); 
myLabelLayer (layer_array [2] , BLUE_PEN, "Simple"); 

pMessage (msgLayer , "Big MoveLayer"); 
for (ktr = 0; ktr < 3; ktr++) 

{ 

if ( IMoveLayer (DUMMY, layer_array [ktr] , -layer_array [ktr] ->bounds .MinX, 0) ) 

error (msgLayer , "MoveLayerO failed."); 
} 

pMessage (msgLayer, "Incrementally increase size"); 
for (ktr = 0; ktr < 5; ktr++) 

{ 

for(ktr_2 = 0; ktr_2 < 3; ktr_2++) 

{ 



if ( ISizeLayer (DUMMY, layer_array [ktr_2] , 1, 1) ) 
error (msgLayer, "SizeLayerO failed."); 



} 



pMessage (msgLayer , "Refresh Smart Refresh Layer"); 
myLabelLayer (layer_array [1] , GREEN_PEN, "Smart"); 
pMessage (msgLayer, "Refresh Simple Refresh Layer"); 
myLabelLayer (layer_array [2] , BLUE_PEN, "Simple"); 

pMessage (msgLayer , "Big SizeLayer" ) ; 
for(ktr = 0; ktr < 3; ktr++) 

{ 

if ( ISizeLayer (DUMMY, layer_array [ktr] , 

SCREEN_W- (layer_array [ktr] ->bounds .MaxX) -1,0) ) 
error (msgLayer , "SizeLayerO failed."); 
} 

pMessage (msgLayer , "Refresh Smart Refresh Layer"); 
myLabelLayer (layer_array [1] , GREEN_PEN, "Smart"); 
pMessage (msgLayer, "Refresh Simple Refresh Layer"); 
myLabelLayer (layer_array [2] , BLUE_PEN, "Simple"); 

pMessage (msgLayer , "ScrollLayer down"); 
for (ktr = 0; ktr < 30; ktr++) 

{ 

for(ktr_2 = 0; ktr_2 < 3; ktr_2++) 

{ 

ScrollLayer (DUMMY, layer_array [ktr_2] , 0, -1); 

} 
} 

pMessage (msgLayer , "Refresh Smart Refresh Layer"); 
myLabelLayer (layer_array [1] , GREEN_PEN, "Smart"); 
pMessage (msgLayer, "Refresh Simple Refresh Layer"); 
myLabelLayer (layer_array [2] , BLUE_PEN, "Simple"); 

pMessage (msgLayer , "ScrollLayer up"); 
for (ktr = 0; ktr < 30; ktr++) 

{ 

for(ktr_2 = 0; ktr_2 < 3; ktr_2++) 

{ 

ScrollLayer (DUMMY, layer_array [ktr_2] , 0, 1); 

} 



pMessage (msgLayer , "Refresh Smart Refresh Layer"); 
myLabelLayer (layer_array [1] , GREEN_PEN, "Smart"); 
pMessage (msgLayer, "Refresh Simple Refresh Layer"); 
myLabelLayer (layer_array [2] , BLUE_PEN, "Simple"); 

Delay (L_DELAY) ; 
} 

/* 

** delete the layer array created by allocLayers () . 

*/ 

VOID disposeLayers (struct Layer *msgLayer, struct Layer *layer_array [] ) 

{ 

WORD ktr; 

for (ktr = 0; ktr < 3; ktr++) 

{ 

if (layer_array [ktr] != NULL) 

{ 

if ( IDeleteLayer (DUMMY, layer_array [ktr] ) ) 

error (msgLayer , "Error deleting layer"); 
} 
} 
} 

/* 



** Create some hard-coded layers. The first must be super-bitmap, with 

** the bitmap passed as an argument. The others must not be super-bitmap. 

** The pointers to the created layers are returned in layer_array. 
* * 

** Return FALSE on failure. On a FALSE return, the layers are 
** properly cleaned up. 

*/ 

BOOL allocLayers (struct Layer *msgLayer, struct Layer *layer_array [] , 
struct BitMap *super_bitmap, struct Layer_Info *theLayerInf o, 
struct BitMap *theBitMap) 

{ 

WORD ktr; 

BOOL create_layer_ok = TRUE; 

for (ktr = 0; 

(ktr < 3) && (create_layer_ok) ; 

ktr++) 

{ 

pMessage (msgLayer , "Create BehindLayer" ) ; 
if (ktr == 0) 

{ 

if ( (layer_array [ktr] = CreateBehindLayer (theLayerlnf o, theBitMap, 
W_L+ (ktr*30) , W_T+ (ktr*30) , W_R+ (ktr*30) , W_B+ (ktr*30) , 
theLayerFlags [ktr] , super_bitmap) ) == NULL) 
create_layer_ok = FALSE; 

} 
else 

{ 

if ( (layer_array [ktr] = CreateBehindLayer (theLayerlnf o, theBitMap, 

W_L+ (ktr*30) , W_T+ (ktr*30) , W_R+ (ktr*30) , W_B+ (ktr*30) , 

theLayerFlags [ktr] , NULL) ) == NULL) 
create_layer_ok = FALSE; 



if (create_layer_ok) 

{ 

pMessage (msgLayer , "Fill the RastPort"); 
SetRast (layer_array [ktr] ->rp, ktr + 1); 
} 
} 

if ( ! create_layer_ok) 

disposeLayers (msgLayer , layer_array) ; 

return (create_layer_ok) ; 
} 

/* 

** Free the bitmap and all bitplanes created by allocBitMap ( ) . 

*/ 

VOID disposeBitMap (struct BitMap *bitmap, LONG depth, LONG width, LONG height) 

{ 

WORD ktr; 

if (NULL != bitmap) 

{ 

for (ktr = 0; ktr < depth; ktr++) 

{ 

if (NULL != bitmap- >Planes [ktr] ) 

FreeRaster (bitmap->Planes [ktr] , width, height); 
} 

FreeMem (bitmap, sizeof (*bitmap) ) ; 
} 



/* 

** Allocate and initialize a bitmap structure. 

*/ 

struct BitMap *allocBitMap (LONG depth, LONG width, LONG height) 

{ 

WORD ktr; 



BOOL bit_map_f ailed = FALSE; 
struct BitMap *bitmap = NULL; 

if (NULL != (bitmap = AllocMem (sizeof ( *bitmap) , NULL) ) ) 

{ 

InitBitMap (bitmap, depth, width, height) ; 

for (ktr = 0; ktr < depth; ktr++) 

{ 

if (NULL == (bitmap->Planes [ktr] = (PLANEPTR) AllocRaster (width, height) ) ) 

bit_map_f ailed = TRUE; 
else 

BltClear (bitmap->Planes [ktr] , RASSIZE (width, height) , 1) ; 

} 
if (bit_map_f ailed) 

{ 

disposeBitMap (bitmap, depth, width, height) ; 
bitmap = NULL; 
} 
} 
return (bitmap) ; 

} 

/* 

** Set up to run the layers example, doLayersO . Clean up when done. 

*/ 

VOID startLayers (struct Layer_Info *theLayerInf o, struct BitMap *theBitMap) 

{ 

struct Layer *msgLayer; 

struct BitMap *theSuperBitMap; 

struct Layer *theLayers [3] = { NULL, NULL, NULL, }; 

if (NULL != (msgLayer = CreateUpf rontLayer ( theLayerlnf o, theBitMap, 
M_L, M_T, M_R, M_B, LAYERSMART, NULL))) 

{ 

pMessage (msgLayer , "Setting up Layers"); 

if (NULL != (theSuperBitMap = allocBitMap (SCREEN_D, SUPER_W, SUPER_H) ) ) 

{ 

if (allocLayers (msgLayer , theLayers, theSuperBitMap, theLayerlnf o, theBitMap)) 

{ 

doLayers (msgLayer , theLayers); 

disposeLayers (msgLayer , theLayers) ; 

} 

disposeBitMap (theSuperBitMap, SCREEN_D, SUPER_W, SUPER_H) ; 

} 
if ( IDeleteLayer (DUMMY, msgLayer)) 

error (msgLayer , "Error deleting layer"); 
} 
} 

/* 

** Set up a low-level graphics display for layers to work on. Layers 
** should not be built directly on Intuition screens, use a low-level 
graphics view. If you need mouse or other events for the layers 
display, you have to get them directly from the input device. The 
** only supported method of using layers library calls with Intuition 
** (other than the InstallClipRegion ( ) call) is through Intuition windows. 



* * 



* * 



** See graphics primitives chapter for details on creating and using the 
** low-level graphics calls. 

*/ 

VOID runNewView(VOID) 

{ 

struct View theView; 

struct View *oldview; 

struct Viewport theViewPort; 

struct Raslnfo theRasInfo; 

struct ColorMap *theColorMap; 

struct Layer_Info *theLayerInf o; 

struct BitMap *theBitMap; 



UWORD *colorpalette; 

WORD ktr; 

/* save current view, to be restored when done */ 
if (NULL != (oldview = Gf xBase->ActiView) ) 

{ 

/* get a Layerlnfo structure */ 

if (NULL != (theLayerlnfo = NewLayerlnf o ( ) ) ) 

{ 

if (NULL != (theColorMap = GetColorMap (4) ) ) 

{ 

colorpalette = (UWORD *) theColorMap- >ColorTable; 

for (ktr = 0; ktr < 4; ktr++) 

*colorpalette++ = colortable [ktr] ; 

if (NULL != (theBitMap = allocBitMap (SCREEN_D, SCREEN_W, SCREEN_H) ) ) 

{ 

InitView (StheView) ; 

InitVPort (StheViewPort) ; 

theView. Viewport = &theViewPort ; 

theViewPort.DWidth = SCREEN_W; 
theViewPort .DHeight = SCREEN_H; 
theViewPort .Raslnf o = StheRasInf o; 
theViewPort .ColorMap = theColorMap; 

theRasInfo.BitMap = theBitMap; 
theRasInfo.RxOf f set = 0; 
theRasInfo.RyOf f set = 0; 
theRasInfo.Next = NULL; 

MakeVPort (StheView, StheViewPort) ; 
MrgCop (StheView) ; 
LoadView (&theView) ; 
WaitTOFO ; 

startLayers (theLayerlnfo, theBitMap) ; 

/* put back the old view, wait for it to become 
** active before freeing any of our display 

*/ 

LoadView (oldview) ; 
WaitTOFO ; 

/* free dynamically created structures */ 
FreeVPortCopLists (StheViewPort) ; 
FreeCprList (theView.LOFCprList) ; 

disposeBitMap (theBitMap, SCREEN_D, SCREEN_W, SCREEN_H) ; 

} 
FreeColorMap (theColorMap) ; /* free the color map */ 

} 

DisposeLayerlnf o (theLayerlnfo) ; 

} 
} 
} 

/* 

** Open the libraries used by the example. Clean up when done. 

*/ 

VOID main(int argc, char **argv) 

{ 

if (NULL != (GfxBase = (struct GfxBase *) OpenLibrary ( "graphics . library" , 33L) ) ) 

{ 

if (NULL != (LayersBase = OpenLibrary ( "layers . library" , 33L) ) ) 

{ 

runNewView ( ) ; 

CloseLibrary ( (struct Library *) LayersBase) ; 

} 

CloseLibrary ( (struct Library *)GfxBase); 



Regions 



Regions allow the application to install clipping rectangles into layers. A clipping rectangle is a rectangular area 
into which the graphics routines will draw. All drawing that would fall outside of that rectangular area is clipped 
(not rendered). 

User clipping regions are linked lists of clipping rectangles created by an application program through the graphics 
library routines described below. By combining together various clipping rectangles, any arbitrary clipping shape 
can be created. Once the region is set up, you use the layers library call lnstallClipRegion() to make the clipping 
region active in a layer. 



Regions are safe to use with layers created by Intuition (i.e. 
available for the creation, manipulation and use of regions. 



windows). The following table describes the routines 



Table 30-4: Functions Used with Regions 



Routine 


Library 


Description 


InstallClipRegionO 


Layers 


Add a clipping region to a layer. 


NewKegion() 


graphics 


ureate a new, empty region. 


DisposeRegion() 


Graphics 


Dispose of an existing region and its rectangles. 


AndHectKegion() 


Graphics 


And a rectangle into a region. 


OrRectRegion() 


Graphics 


Or a rectangle into a region. 


XorRectRegion() 


Graphics 


Exclusive- or a rectangle into a region. 


ClearRectRegion() 


Graphics 


Clear a rectangular portion of a region. 


AndRegionRegion() 


Graphics 


/Anc/two regions together. 


OrRegionRegion() 


Graphics 


Or two regions together. 


XorRegionRegion() 


Graphics 


Exclusive-or two regions together. 


ClearRegion() 


Graphics 


Clear a region. 



With these functions, the application can selectively update a custom-shaped part of a layer without disturbing any 
of the other layers that might be present. 

Never Modify the DamageList of a Layer Directly. Use the routine InstallClipRegionO to add 
clipping to the layer. The regions installed by InstallClipRegionO are independent of the 
layer's DamageList and use of user clipping regions will not interfere with optimized window 
refreshing. 

Do Not Modify A Region After It Has Been Added. After a region has been added with 
InstallClipRegionO, the program may not modify it until the region has been removed with 
another call to InstallClipRegionO. 
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Creating and Deleting Regions 



You allocate a Region data structure with the NewRegion() call. 

struct Region *NewRegion ( void ) ; 

The NewRegion() function allocates and initializes a Region structure that has no drawable areas defined in it. If 
the application draws through a new region, nothing will be drawn as the region is empty. The application must 
add rectangles to the region before any graphics will appear. 

Use DisposeRegion() to free the Region structure when you are done with it. 

void DisposeRegion ( struct Region *region ); 



DisposeRegion() returns all memory associated with a region to the system and deallocates all rectangles that 
have been linked to it. 



Don't Forget to Free Your Rectangles. All of the functions that add rectangles to the region 
make copies of the rectangles. If the program allocates a rectangle, then adds it to a region, it 
still must deallocate the rectangle. The call to DisposeRegion() will not deallocate rectangles 
explicitly allocated by the application. 

Installing Regions 

Use the function InstallClipRegionQ to install the region. 

struct Region *InstallClipRegion ( struct Layer *layer, struct Region *region ); 

This installs a transparent clipping region to a layer. All subsequent graphics calls will be clipped to this region. 
The region must be removed with a second call to lnstallClipRegion() before removing the layer. 

/* 

** Sample installation and removal of a clipping region 

*/ 

register struct Region *new_region ; 

register struct Region *old_region ; 

/* If the application owns the layer and has not installed a region, 

** old_region will return NULL here. 

*/ 

old_region = InstallClipRegion (win->WLayer , new_region) ; 

/* draw into the layer or window */ 

if (NULL != (old_region = InstallClipRegion (win- >WLayer, old_region) ) ) 

{ 

/* throw the used region away. This region could be saved and 
** used again later, if desired by the application. 

*/ 
DisposeRegion (new_region) ; 

} 
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A Warning About InstallClipRegionQ. The program must not call lnstallClipRegion() inside of 
a Begin/EndRefresh() or Begin/EndUpdate() pair. The following code segment shows how 
to modify the user clipping region when using these calls. See the Autodoc for 
BeginRefresh() for more details. 

register struct Region *new_region ; 
register struct Region *old_region ; 

/* you have to have already setup the new_region and old_region */ 

BeginRefresh (window) ; 

/* draw through the damage list */ 

/* into the layer or window */ 

EndRefresh (window, FALSE); /* keep the damage list */ 

old_region = InstallClipRegion (win->WLayer, new_region) ; 

BeginRefresh (window) ; 

/* draw through the damage list and the new_region */ 

/* into the layer or window */ 

EndRefresh (window, FALSE); /* keep the damage list */ 

/* put back the old region */ 

new_region = InstallClipRegion (win->WLayer, old_region) ; 

BeginRefresh (window) ; 

EndRefresh (window, TRUE); /* remove the damage list */ 



old_region = InstallClipRegion (win->WLayer , new_region) ; 

BeginRef resh (window) ; 

/* draw through the new_region only into the layer or window */ 

EndRef resh (window, FALSE); 

/* finally get rid of the new region, old_region still installed */ 
if (NULL != (new_region = InstallClipRegion (win- >WLayer, old_region) ) ) 
DisposeRegion (new_region) ; 

Changing a Region 

Regions may be modified by performing logical operations with rectangles, or with other regions. 

Reuse Your Rectangles. In all of the rectangle and region routines the clipping rectangle is 
copied into the region. This means that a single clipping rectangle (Rectangle structure) may 
be used many times by simply changing the x and y values. The application need not create a 
new instance of the Rectangle structure for each rectangle added to a region. 

For instance: 

extern struct Region *RowRegion; /* created elsewhere */ 

WORD ktr; 

struct Rectangle rect; 

for (ktr = 1; ktr < 6; ktr++) 

{ 

rect. MinX = 5 0; 

rect.MaxX = 315; 

rect.MinY = (ktr * 10) - 5 ; 

rect.MaxY = (ktr * 10); 

if ( !OrRectRegion (RowRegion, &rect) ) 
clean_exit (RETURN_WARN) ; 
} 
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Rectangles and Regions 

There are four functions for changing a region through logical operations with a rectangle. 

BOOL OrRectRegion ( struct Region *region, struct Rectangle *rectangle 

void AndRectRegion ( struct Region *region, struct Rectangle *rectangle 

BOOL XorRectRegion ( struct Region *region, struct Rectangle *rectangle 

BOOL ClearRectRegion ( struct Region *region, struct Rectangle *rectangle 

OrRectRegion() modifies a region structure by or'inga clipping rectangle into the region. When the application 
draws through this region (assuming that the region was originally empty), only the pixels within the clipping 
rectangle will be affected. If the region already has drawable areas, they will still exist, this rectangle is added to 
the drawable area. 

AndRectRegion() modifies the region structure by and'ing a clipping rectangle into the region. Only those pixels 
that were already drawable and within the rectangle will remain drawable, any that are outside of it will be clipped 
in future. 

XorRectRegion() applies the rectangle to the region in an exclusive-or mode. Within the given rectangle, any 
areas that were drawable become clipped, any areas that were clipped become drawable. Areas outside of the 
rectangle are not affected. 

ClearRectRegion() clears the rectangle from the region. Within the given rectangle, any areas that were 
drawable become clipped. Areas outside of the rectangle are not affected. 



Regions and Regions 

As with rectangles and regions, there are four layers library functions for combining regions with regions: 

BOOL AndRegionRegion ( struct Region *srcRegion, struct Region *destRegion ) ; 

BOOL OrRegionRegion ( struct Region *srcRegion, struct Region *destRegion ); 

BOOL XorRegionRegion ( struct Region *srcRegion, struct Region *destRegion ); 

void ClearRegion ( struct Region *region ) ; 

AndRegionRegion() performs a logical and operation on the two regions, leaving the result in the second region. 
The operation leaves drawable areas wherever the regions drawable areas overlap. That is, where there are 
drawable areas in both region 1 and region 2, there will be drawable areas left in the result region. 

OrRegionRegion() performs a logical or operation on the two regions, leaving the result in the second region. 
The operation leaves drawable areas wherever there are drawable areas in either region. That is, where there are 
drawable areas in either region 1 or region 2, there will be drawable areas left in the result region. 

XorRegionRegion() performs a logical exclusive-or operation on the two regions, leaving the result in the second 
region. The operation leaves drawable areas wherever there are drawable areas in either region but not both. 
That is, where there are drawable areas in either region 1 or region 2, there will be drawable areas left in the 
result region. But where there are drawable areas in both region 1 and region 2, there will not be drawable areas 
left in the result region. 

ClearRegion() puts the region back to the same state it was in when the region was created with NewRegion(), 
that is, no areas are drawable. 
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Regions Example 

The following example shows the use of the layers library call InstallClipRegionQ, as well as simple use of the 
graphic library regions functions. Be aware that it uses Release 2 functions for opening and closing Intuition 
windows. 



/* The following example shows the use of the layers library call 

InstallClipRegion ( ) , as well as simple use of the graphics library 
regions functions. Be aware that it uses Release 2 functions for 
opening and closing Intuition windows. 



• * 

• * 

• * 

• * 

• * 

• * 

• * 

• * 

• * 

*/ 



clipping. c 

SAS/C 5.10a 

lc -bl -cfist -v -y clipping 

blink FROM LIB:c.o clipping. o TO clipping LIB LIB :1c. lib LIB : amiga . lib 



/* Force use of new variable names to help prevent errors */ 
#define INTuT_V36_NAMES_ONLY 

#include <exec/types .h> 
#include <intuition/intuition.h> 
#include <intuition/intuitionbase . h> 
#include <graphics/displayinf o.h> 

#include <clib/exec_protos . h> 
#include <clib/dos_protos . h> 
#include <clib/intuition_protos . h> 
#include <clib/graphics_protos . h> 
#include <clib/layers_protos . h> 

#include <stdio.h> 

#ifdef LATTICE 

int CXBRK(void) { return(O); } /* Disable Lattice CTRL/C handling */ 

int chkabort (void) { return(O); } /* really */ 

#endif 

#define MY WIN WIDTH (300) 



#define MY_WIN_HEIGHT (100) 

struct IntuitionBase *IntuitionBase; 
struct Gf xBase *Gf xBase; 
struct Library *LayersBase; 

/* 

** unclipWindow ( ) 

** Used to remove a clipping region installed by clipWindowO or 
** clipWindowToBorders ( ) , disposing of the installed region and 
** reinstalling the region removed. 

*/ 

void unclipWindow (struct Window *win) 

{ 

struct Region *old_region; 

/* Remove any old region by installing a NULL region, 
** then dispose of the old region if one was installed. 

*/ 

if (NULL != (old_region = InstallClipRegion (win->WLayer, NULL))) 

DisposeRegion (old_region) ; 
} 

/* 

** clipWindowO 

** Clip a window to a specified rectangle (given by upper left and 
** lower right corner.) the removed region is returned so that it 
** may be re-installed later. 

*/ 

struct Region *clipWindow (struct Window *win, 

LONG minX, LONG minY, LONG maxX, LONG maxY) 

{ 

struct Region *new_region; 

struct Rectangle my_rectangle; 

/* set up the limits for the clip */ 
my_rectangle .MinX = minX; 
my_rectangle .MinY = minY; 
my_rectangle .MaxX = maxX; 
my_rectangle .MaxY = maxY; 

/* get a new region and OR in the limits. */ 
if (NULL != (new_region = NewRegion ( ) ) ) 

{ 

if (FALSE == OrRectRegion (new_region, &my_rectangle) ) 

{ 

DisposeRegion (new_region) ; 

new_region = NULL; 

} 



/* Install the new region, and return any existing region. 

** If the above allocation and region processing failed, then 

** new_region will be NULL and no clip region will be installed. 

*/ 

return (InstallClipRegion (win->WLayer , new_region) ) ; 

} 

/* 

** clipWindowToBorders ( ) 

** clip a window to its borders. 

** The removed region is returned so that it may be re-installed later. 

*/ 

struct Region * clipWindowToBorders (struct Window *win) 

{ 

return (clipWindow (win, win->BorderLef t , win->BorderTop, 

win->Width - win->BorderRight - 1, win->Height - win->BorderBottom - 1) ) 



/* 

** Wait for the user to select the close gadget. 



*/ 

VOID wait_f or_close (struct Window *win) 

{ 

struct IntuiMessage *msg; 

SHORT done; 

done = FALSE; 

while (FALSE == done) 

{ 

/* we only have one signal bit, so we do not have to check which 

** bit broke the WaitO. 

*/ 

Wait(lL << win->UserPort->mp_SigBit) ; 

while ( (FALSE == done) && 

(NULL != (msg = (struct IntuiMessage *) GetMsg (win->UserPort) ) ) ) 

{ 

/* use a switch statement if looking for multiple event types */ 
if (msg->Class == IDCMP^CLOSEWINDOW) 
done = TRUE ; 

ReplyMsg ( (struct Message *)msg); 
} 
} 
} 

/* 

** Simple routine to blast all bits in a window with color three to show 
** where the window is clipped. After a delay, flush back to color zero 
** and refresh the window borders. 

*/ 

VOID draw_in_window (struct Window *win, UBYTE *message) 

{ 

printf ( "%s . . . " , message); f flush (stdout) ; 

SetRast (win->RPort , 3); 

Delay (200) ; 

SetRast (win->RPort, 0) ; 

Ref reshWindowFrame (win) ; 

printf ( "done\n" ) ; 

} 

/* 

** Show drawing into an undipped window, a window clipped to the 
** borders and a window clipped to a random rectangle. It is possible 
** to clip more complex shapes by AND'ing, OR'ing and exclusive-OR' ing 
** regions and rectangles to build a user clip region. 

** This example assumes that old regions are not going to be re-used, 
** so it simply throws them away. 

*/ 

VOID clip_test (struct Window *win) 

{ 

struct Region *old_region; 

draw_in_window (win, "Window with no clipping"); 

/* if the application has never installed a user clip region, 
** then old_region will be NULL here. Otherwise, delete the 
** old region (you could save it and re-install it later...) 

*/ 

if (NULL != (old_region = clipWindowToBorders (win) ) ) 

DisposeRegion (old_region) ; 
draw_in_window (win, "Window clipped to window borders"); 
unclipWindow (win) ; 

/* here we know old_region will be NULL, as that is what we 
** installed with unclipWindow ( ) . . . 

*/ 

if (NULL != (old_region = clipWindow (win, 20 , 20 , 100 , 50) ) ) 

DisposeRegion (old_region) ; 
draw_in_window (win, "Window clipped from (20,20) to (100,50)"); 
unclipWindow (win) ; 



wait_f or_close (win) ; 
} 

/* Open and close resources, call the test routine when ready. 

*/ 

VOID main(int argc, char **argv) 

{ 

struct Window *win; 

if (NULL != (IntuitionBase = 

(struct IntuitionBase *) OpenLibrary ( "intuition. library" , 37) ) ) 

{ 

if (NULL != (GfxBase = (struct GfxBase *) OpenLibrary ( "graphics . library" , 37) ) ) 

{ 

if (NULL != (LayersBase = OpenLibrary ( "layers . library" , 37) ) ) 

{ 

if (NULL != (win = OpenWindowTags (NULL, 

WA_Width, MY_WIN_WIDTH, 

WA_Height , MY_WIN_HEIGHT , 

WA_IDCMP, IDCMP_CLOSEWINDOW, 

WA_CloseGadget, TRUE, 

WA_DragBar , TRUE , 

WA_Activate, TRUE, 

TAG_END) ) ) 

{ 

clip_test (win) ; 

CloseWindow (win) ; 

} 
CloseLibrary (LayersBase) ; 

} 
CloseLibrary ( (struct Library *)GfxBase); 

} 
CloseLibrary ( (struct Library *) IntuitionBase) ; 



} 



Function Reference 
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The following are brief descriptions of the layers library functions and related routines from the graphics library. 
See the Amiga ROM Kernel Reference Manual: Includes and Autodocs for details on each function call. 

Table 30-5: Layers Library Functions 



Function 


Description 


NewLayerlnfo() 


Allocating a Layerjnfo structure. 


DisposeLayerlnfo() 


Deallocating a Layerjnfo structure. 


CreateUpfrontLayerQ 


Make a new layer in front of others. 


CreateBehindLayer() 


Make a new layer behind others. 


DeleteLayer() 


Remove and delete an existing layer. 


MoveLayer() 


Change the position (not depth) of a layer. 


SizeLayer() 


Change the size of a layer. 


ScrollLayer() 


Change the internal coordinates of a layer. 


BehindLayer() 


Depth arrange a layer behind others. 


UpfrontLayer() 


Depth arrange a layer in front of others. 


MoveLayerlnFrontOf() 


Depth arrange a layer to a specific position. 


wmcnLayer() 


hind the rrontmost layer at a position. 


SwapBitsRastPortClipRect() Fast, non-layered and non-damaging display operation. 


BeginUpdate() 


syncnronize opumizea rerresning Tor layer. 


EndUpdate() 


End optimized layer refresh. 


LockLayer() 


Lock out rendering in a single layer. 


UnlockLayer() 


Release LockLayer() lock. 


LockLayers() 


Lock out rendering in all layers of a display. 


UnlockLayers() 


Release LockLayers() lock. 


LockLayerlnfo() 


Gain exclusive access to the display's layers. 


UnlockLayerlnfo() 


Release LockLayerlnfo() lock. 


lnstallCllpRegion() 


Acid a clipping region to a layer. 



The following routines from graphics library are also required for certain layers library functions: 



Routine 


Description 


LockLayerRom() 


Same as LockLayer(), from layers library. 


UnlockLayerRom() 


Release LockLayerRom() lock. 


AttemptLockLayerRom() Lock layer only if it is immediately available. 


NewRegion() 


Create a new, empty region. 


DIsposeReglonO 


Dispose of an existing region and its rectangles. 


AndRectReglon() 


and a rectangle into a region. 


OrRectReglon() 


OR a rectangle into a region. 


XorRectRegion() 


Exclusive-OR a rectangle into a region. 


ClearRectRegion() 


Clear a region. 


AndRegionRegion() 


AND two regions together. 


OrRegionRegion() 


OR two regions together. 


XorRegionRegion() 


Exclusive-OR two regions together. 


ClearReglonQ 


Clear a region. 
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Chapter 31 

Commodities Exchange Library 

This chapter describes Commodities Exchange, the library of routines used to add a custom input handler to the 
Amiga. With Commodities Exchange, any program function can be associated with key combinations or other 
input events globally allowing the creation utility programs that run in the background for all tasks. 

Custom Input Handlers 

The input.device has a hand in almost all user input on the Amiga. It gathers input events from the keyboard, the 
gameport (mouse), and several other sources, into one input "stream". Special programs called input event 
handlers intercept input events along this stream, examining and sometimes changing the input events. Both 
Intuition and the console device use input handlers to process user input. 




Figure 31-1 : The Amiga Input Stream 

Using the input.device, a program can introduce its own custom handler into the chain of input handlers at almost 
any point in the chain. "Hot key" programs, shell pop-up programs, and screen blankers all commonly use 
custom input handlers to monitor user input before it gets to the Intuition input handler. 
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Figure 31-2: A Custom Input Handler 

Custom input handlers do have their drawbacks, however. Not only are these handlers hard to program, but 
because there is no standard way to implement and control them, multiple handlers often do not work well 
together. Their antisocial behavior can result in load order dependencies and incompatibilities between different 
custom input handlers. Even for the expert user, having several custom input handlers coexist peacefully can be 
next to impossible. 




Figure 31-3: The Commodities Network 
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Commodities Exchange eliminates these problems by providing a simple, standardized way to program and 
control custom input handlers. It is divided into three parts: an Exec library, a controller program, and some 
amiga.lib functions. 

The Exec library is called commodities. library. When it is first opened, commodities. library establishes a single 
input handler just before Intuition in the input chain. When this input handler receives an input event, it creates a 
CxMessage (Commodities Exchange Message) corresponding to the input event, and diverts the CxMessage 
through the network of Commodities Exchange input handlers (Figure 31-3). 

These handlers are made up of trees of different CxObjects (Commodities Exchange Objects), each of which 
performs a simple operation on the CxMessages. Any CxMessages that exit the network are returned to the 
input.device's input stream as input events. 

Through function calls to the commodities. library, an application can install a custom input handler. A 
Commodities Exchange application, sometimes simply referred to as a commodity, uses the CxObject primitives 
to do things such as filter certain CxMessages, translate CxMessages, signal a task when a CxObject receives 
a CxMessage, send a message when a CxObject receives a CxMessage, or if necessary, call a custom function 
when a CxObject receives a CxMessage. 

The controller program is called Commodities Exchange. The user can monitor and control all the currently 
running Commodities Exchange applications from this one program. The user can enable and disable a 
commodity, kill a commodity, or, if the commodity has a window, ask the commodity to show or hide its window. 
When the user requests any of these actions, the controller program sends the commodity a message, telling it 
which action to perform. 

The third component of Commodities Exchange is its scanned library functions. These functions are part of the 
amiga.lib scanned library. They do a lot of the work involved with parsing command lines and Tool Types. 

Commodities Exchange is ideal for programs like hot keys/pop ups, screen blankers, and mouse blankers that 
need to monitor all user input. Commodities Exchange should never be used as an alternate method of receiving 
user input for an application. Other applications depend on getting user input in some form or another from the 
input stream. A greedy program that diverts input to itself rather than letting the input go to where the user 
expects it can seriously confuse the user, not to mention compromise the advantages of multitasking. 



CxObjects 



CxObjects are the basic building blocks used to construct a commodity. A commodity uses CxObjects to take 
care of all manipulations of CxMessages. When a CxMessage "arrives" at a CxObject, that CxObject carries 
out its primitive action and then, if it has not deleted the CxMessage, it passes the CxMessage on to the next 



CxObject. A commodity links together CxObjects into a tree, organizing these simple action objects to perform 
some higher function. 

A CxObject is in one of two states, active or inactive. An active CxObject performs its primitive action every time 
it receives a CxMessage. If a CxObject is inactive, CxMessages bypass it, continuing to the CxObject that 
follows the inactive one. By default, all CxObjects except the type called brokers are created in the active state. 
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Currently, there are seven types of CxObjects (Table 31-1). 

Object Type Purpose 

Broker Registers a new commodity with the commodity network 

Filter Accepts or rejects input events based on criteria set up by the application 

Sender Sends a message to a message port 

Translate Replaces the input event with a different one 

Signal Signals a task 

Custom Calls a custom function provided by the commodity 

Debug Sends debug information out the serial port 

Table 31-1 : Commodities Exchange Object Types 

Installing A Broker Object 

The Commodities Exchange input handler maintains a master list of CxObjects to which it diverts input events 
using CxMessages. The CxObjects in this master list are a special type of CxObject called brokers. The only 
thing a broker CxObject does is divert CxMessages to its own personal list of CxObjects. A commodity creates 
a broker and attaches other CxObjects to it. These attached objects take care of the actual input handler related 
work of the commodity and make up the broker's personal list. 

The first program listing, Broker. c, is a very simple example of a working commodity. It serves only to illustrate 
the basics of a commodity, not to actually perform any useful function. It shows how to set up a broker and 
process commands from the controller program. 

Besides opening commodities. library and creating an Exec message port, setting up a commodity requires 
creating a broker. The function CxBroker() creates a broker and adds it to the master list. 

CxObj *CxBroker (struct NewBroker *nb, long *error) ; 

CxBroker()'s first argument is a pointer to a NewBroker structure: 

struct NewBroker { 

BYTE nb_Version; /* There is an implicit pad byte after this BYTE */ 

BYTE *nb_Name ; 

BYTE *nb_Title; 

BYTE *nb_Descr; 

SHORT nb_Unique; 

SHORT nb_Flags ; 

BYTE nb_Pri; /* There is an implicit pad byte after this BYTE */ 

struct MsgPort *nb_Port; 

WORD nb_ReservedChannel ; /* Unused, make zero for future compatibility */ 

}; 

Commodities Exchange gets all the information it needs about the broker from this structure. NewBroker's 
nb_Version field contains the version number of the NewBroker structure. This should be set to NB_VERSION 
which is defined in <libraries/commodities.h>. The nb_Name, nb_Title, and nb_Descr point to strings which 
hold the name, title, and description of the broker. The two bit fields, nb_Unique and nb_Flags, toggle certain 
features of Commodities Exchange based on their values. They are discussed in detail later in this chapter. 

The nb_Pri field contains the broker's priority. Commodities Exchange inserts the broker into the master list 
based on this number. Higher priority brokers get CxMessages before lower priority brokers. 
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CBERR_OK 





/ 


CBERR_SYSERR 


1 


/ 


CBERR_DUP 


2 


/ 


CBERR_VERSION 


3 


/ 



CxBroker()'s second argument is a pointer to a LONG. If this pointer is not NULL, CxBroker() fills in this field 
with one of the following error return codes from <libraries/commodities.h>: 

No error */ 

System error , no memory, etc */ 

uniqueness violation */ 

didn't understand nb_VERSION */ 

Once the broker object is created with CxBroker(), it must be activated with ActivateCxObj(). 

oldactivationvalue = LONG ActivateCxObj (CxObj *co, long newactivationvalue) ; 

After successfully completing the initial set up and activating the broker, a commodity can begin its input 
processing loop waiting for CxMessages to arrive. 



CxMessages 



There are actually two types of CxMessages. The first, CXMJ EVENT, corresponds to an input event and travels 
through the Commodities Exchange network. The other type, CXM_COMMAND, carries a command to a 
commodity. A CXM_COMMAND normally comes from the controller program and is used to pass user commands 
on to a commodity. A commodity receives these commands through an Exec message port that the commodity 
sets up before it calls CxBroker(). The NewBroker's nb_Port field points to this message port. A commodity 
can tell the difference between the two types of CxMessages by calling the CxMsgType() function. 

ULONG CxMsgType ( CxMsg *cxm 
UBYTE *CxMsgData( CxMsg *cxm 
LONG CxMsgID ( CxMsg *cxm 

A CxMessage not only has a type, it can also have a data pointer as well as an ID associated with it. The data 
associated with a CXMJEVENT CxMessage is an InputEvent structure. By using the CxMsgData() function, a 
commodity can obtain a pointer to the corresponding InputEvent of a CXMJEVENT message. Commodities 
Exchange gives an ID of zero to any CXMJEVENT CxMessage that it introduces to the Commodities network 
but certain CxObjects can assign an ID to them. 

For a CXM_COMMAND CxMessages, the data pointer is generally not used but the ID specifies a command 
passed to the commodity from the user operating the controller program. The CxMsglDQ macro extracts the ID 
from a CxMessage. 

A Simple Commodity Example 

The example below, Broker. c, receives input from one source, the controller program. The controller program 
sends a CxMessage each time the user clicks its Enable, Disable, or Kill gadgets. Using the CxMsglD() function, 
the commodity finds out what the command is and executes it. 

/* The example below, Broker. c, receives input from one source, the 

* controller program. The controller program sends a CxMessage each 

* time the user clicks its Enable, Disable, or Kill gadgets. Using the 

* CxMsglDO function, the commodity finds out what the command is and 

* executes it. 

* broker. c - Simple skeletal example of opening a broker 

* compiled with SASC 5.10 

* LC -bo -cfist -v broker. c 

* Blink FROM LIB : c . o, broker . o TO broker LIBRARY LIB : LC . lib, LIB : Amiga . lib 

*/ 

#include <exec/libraries . h> 
#include <libraries/commodities . h> 
#include <dos/dos.h> 
#include <clib/exec_protos . h> 
#include <clib/alib_protos . h> 
#include <clib/alib_stdio_protos . h> 
#include <clib/commodities_protos . h> 



#ifdef LATTICE 

int CXBRK(void) { return(O); } /* Disable Lattice CTRL/C handling */ 

int chkabort (void) { return(O); } 

#endif 

void main (void) ; 

void ProcessMsg (void) ; 

struct Library *CxBase; 

CxObj *broker; 

struct MsgPort *broker_mp; 

ULONG cxsigflag; 

struct NewBroker newbroker = { 

NB_VERSION, /* nb_Version - Version of the NewBroker structure */ 

"RKM broker", /* nb_Name - Name Commodities uses to identify this commodity */ 

"Broker", /* nb_Title - Title of commodity that appears in CXExchange */ 

"A simple example of a broker", /* nb_Descr - Description of the commodity */ 

0, /* nb_Unique - Tells CX not to launch another commodity with same name */ 

0, /* nb_Flags - Tells CX if this commodity has a window */ 

0, /* nb_Pri - This commodity's priority */ 

0, /* nb_Port - MsgPort CX talks to */ 

/* nb_ReservedChannel - reserved for later use */ 

}; 

void main (void) 

{ 

CxMsg *msg; 

/* Before bothering with anything else, open the library */ 
if (CxBase = OpenLibrary ( "commodities . library" , 37L) ) 

{ 

/* Commodities talks to a Commodities application through */ 
/* an Exec Message port, which the application provides */ 
if (broker_mp = CreateMsgPort ( ) ) 

{ 

newbroker . nb_Port = broker_mp; 

/* The commodities . library function CxBrokerO adds a borker to the 

* master list. It takes two arguments, a pointer to a NewBroker 

* structure and a pointer to a LONG. The NewBroker structure contains 

* information to set up the broker. If the second argument is not 

* NULL, CxBroker will fill it in with an error code. 

*/ 

if (broker = CxBroker (&newbroker , NULL)) 

{ 

cxsigflag = 1L << broker_mp->mp_SigBit ; 

/* After it's set up correctly, the broker has to be activated */ 
ActivateCxObj (broker, 1L) ; 

/* the main processing loop */ 
ProcessMsg ( ) ; 

/* It's time to clean up. Start by removing the broker from the 

* Commodities master list. The DeleteCxObjAll ( ) function will 

* take care of removing a CxObject and all those connected 

* to it from the Commodities network 

*/ 

DeleteCxObj (broker) ; 

/* Empty the port of CxMsgs */ 
while (msg = (CxMsg *) GetMsg (broker_mp) ) 
ReplyMsg ( (struct Message *)msg); 

} 

DeletePort (broker_mp) ; 

} 

CloseLibrary (CxBase) ; 



} 
} 



void ProcessMsg (void) 

{ 

CxMsg *msg; 

ULONG sigrcvd, msgid, msgtype; 
LONG returnvalue = 1L; 

while (returnvalue) 

{ 

/* wait for something to happen */ 

sigrcvd = Wait (SIGBREAKF_CTRL_C | cxsigflag) ; 

/* process any messages */ 

while (msg = (CxMsg *) GetMsg (broker_mp) ) 

{ 

/* Extract necessary information from the CxMessage and return it */ 
msgid = CxMsgID (msg) ; 
msgtype = CxMsgType (msg) ; 
ReplyMsg ( (struct Message *)msg); 

switch (msgtype) 

{ 

case CXM_IEVENT: 

/* Shouldn't get any of these in this example */ 

break; 
case CXM_COMMAND: 

/* Commodities has sent a command */ 

printf("A command: " ) ; 

switch (msgid) 

{ 

case CXCMD_DISABLE: 

printf ( "CXCMD_DISABLE\n" ) ; 

/* The user clicked Commodities Exchange disable 
* gadget better disable 

*/ 

ActivateCxObj (broker, OL) ; 

break; 
case CXCMD_ENABLE : 

/* user clicked enable gadget */ 

printf ( "CXCMD_ENABLE\n" ) ; 

ActivateCxObj (broker, 1L) ; 

break; 
case CXCMD_KILL: 

/* user clicked kill gadget, better quit */ 

printf ( "CXCMD_KILL\n" ) ; 

returnvalue = OL; 

break; 

} 

break; 
default : 

printf ( "Unknown msgtype\n"); 
break; 
} 
} 

/* Test to see if user tried to break */ 
if (sigrcvd & SIGBREAKF_CTRL_C) 

{ 

returnvalue = OL; 

printf ("CTRL C signal break\n"); 
} 
} 
} 

Notice that Broker.c uses Ctrl-C as a break key. The break key for any commodity should be Ctrl-C. 
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Controller Commands 

The commands that a commodity can receive from the controller program (as defined in 
< libraries/commodities. h>) are : 



CXCMD_ 


_DISABLE 


/* 


CXCMD_ 


_ENABLE 


/* 


CXCMD_ 


_KILL 


/* 


CXCMD_ 


_APPEAR 


/* 


CXCMD_ 


_DISAPPEAR 


/* 



please disable yourself */ 

please enable yourself */ 

go away for good */ 

open your window, if you can */ 

hide your window */ 

The CXCMD_DISABLE, CXCMD_ENABLE, and CXCMD_KILL commands correspond to the similarly named 
controller program gadgets, Disable, Enable, and Kill; CXCMD_APPEAR and CXCMD_DISAPPEAR correspond 
to the controller program gadgets, Show and Hide. These gadgets are ghosted in Broker. c because it has no 
window (It doesn't make much sense to give the user a chance to click the Show and Hide gadgets). In order to 
do this, Broker.c has to tell Commodities Exchange to ghost these gadgets. When CxBroker() sets up a broker, 
it looks at the NewBroker.nb_Flags field to see if the COF_SHOW_HIDE bit (from <libraries/commodities.h>) is 
set. If it is, the "Show" and "Hide" gadgets for this broker will be selectable. Otherwise they are ghosted and 
disabled. 

Shutting Down the Commodity 

Shutting down a commodity is easy. After replying to all CxMessages waiting at the broker's message port, a 
commodity can delete its CxObjects. The DeleteCxObjQ function removes a single CxObjectfrom the 
Commodities network. DeleteCxObjAIIQ removes multiple objects. 

void DeleteCxObj ( CxObj *co ) ; 

void DeleteCxObjAll ( CxObj *delete_co ) ; 

If a commodity has a lot of CxObjects, deleting each individually can be a bit tedious. DeleteCxObjAIIQ will 
delete a CxObject and any other CxObjects that are attached to it. The HotKey.c example given later in this 
chapter uses this function to delete all its CxObjects. A commodity that uses DeleteCxObjAIIQ to delete all its 
CxObjects should make sure that they are all connected to the main one. (See the section "Connecting 
CxObjects" below.) 

After deleting its CxObjects, a commodity must take care of any CxMessages that might have arrived at the 
message port just before the commodity deleted its objects. 

while (msg = (CxMsg *) GetMsg (broker_mp) ) 
ReplyMsg ( (struct Message *)msg); 



Commodity Tool Types 



A goal of Commodities Exchange is to improve user control over input handlers. One way in which it 
accomplishes this goal is through the use of standard icon Tool Types. The user will expect commodities to 
recognize the set of standard Tool Types: 

CX_PRIORITY 

CX_POPUP 

CX_POPKEY 
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CX_PRIORITY lets the user set the priority of a commodity. The string "CX_PRIORITY=" is a number from -128 
to 127. The higher the number, the higher the priority of the commodity, giving it access to input events before 
lower priority commodities. All commodities should recognize CX_PRIORITY. 

CX_POPUP and CX_POPKEY are only relevant to commodities with a window. The string "CX_POPUP=" should 
be followed by a "yes" or "no", telling the commodity if it should or shouldn't show its window when it is first 
launched. CX_POPKEY is followed by a string describing the key to use as a hot key for making the commodity's 
window appear (pop up). The description string for CX_POPKEY describes an input event. The specific format of 
the string is discussed in the next section ("Filter Objects and the Input Description String"). 

Commodities Exchange's support library functions simplify parsing arguments from either the Workbench or the 
Shell (CLI). A Workbench launched commodity gets its arguments directly from the Tool Types in the 
commodity's icon. Shell launched commodities get their arguments from the command line, but these arguments 
look exactly like the Tool Types from the commodity's icon. For example, the following command line sets the 



priority of a commodity called HotKey to 5: 

HotKey "CX_PRIORITY=5" 

Commodities Exchange has several support library functions used to parse arguments: 

tooltypearray = UBYTE **ArgArrayInit (LONG argc, UBYTE **argv) ; 
void ArgArrayDone (void) ; 

tooltypevalue = STRPTR ArgSt ring (UBYTE **tooltypearray, STRPTR tooltype, 

STRPTR defaultvalue) ; 
tooltypevalue = LONG *ArgInt (UBYTE **tooltypearray , STRPTR tooltype, 

LONG defaultvalue) ; 

ArgArraylnit() initializes a Tool Type array of strings which it creates from the startup arguments, argc and argv. 
It doesn't matter if these startup arguments come from the Workbench or from a Shell, ArgArraylnit() can extract 
arguments from either source. Because ArgArraylnitQ uses some icon. library functions, a commodity is 
responsible for opening that library before using the function. 

ArgArraylnit() also uses some resources that must be returned to the system when the commodity is done. 
ArgArrayDoneQ performs this clean up. Like ArgArraylnit(), ArgArrayDoneQ uses icon. library, so the library 
has to remain open until ArgArrayDone() is finished. 

The support library has two functions that use the Tool Type array set up by ArgArraylnit(), ArgString() and 
Arglnt(). ArgStringO scans the Tool Type array for a specific Tool Type. If successful, it returns a pointer to the 
value associated with that Tool Type. If it doesn't find the Tool Type, it returns the default value passed to it. 
Arglnt() is similar to ArgString(). It also scans the ArgArraylnit()'s Tool Type array, but it returns a LONG rather 
than a string pointer. ArglntQ extracts the integer value associated with a Tool Type, or, if that Tool Type is not 
present, it returns the default value. 

Of course, these Tool Type parsing functions are not restricted to the standard Commodities Exchange Tool 
Types. A commodity that requires any arguments should use these functions along with custom Tool Types to 
obtain these values. Because the Commodities Exchange standard arguments are processed as Tool Types, the 
user will expect to enter other arguments as Tool Types too. 
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Filter Objects and Input Description Strings 

Because not all commodities are interested in every input event that makes it way down the input chain, 
Commodities Exchange has a method for filtering them. A filter CxObject compares the CxMessages it receives 
to a pattern. If a CxMessage matches the pattern, the filter diverts the CxMessage down its personal list of 
CxObjects. 

CxObj *CxFilter (UBYTE *descriptionstring) ; 

The C macro CxFilter() (defined in <libraries/commodities.h>) returns a pointer to a filter CxObject. The macro 
has only one argument, a pointer to a string describing which input events to filter. The following regular 
expression outlines the format of the input event description string (CX_POPKEY uses the same description string 
format): 

[class] { [-] (qualifier | synonym) } [ [-] upstroke] [highmap | ANSICode] 

Class can be any one of the class strings in the table below. Each class string corresponds to a class of input 
event as defined in <devices/inputevent.h>. Commodities Exchange will assume the class is rawkey if the class 
is not explicitly stated. 

Class String Input Event Class 

"rawkey" IECLASS_RAWKEY 

"rawmouse" IECLASS_RAWMOUSE 

"event" IECLASS_EVENT 

"pointerpos " IECLASS_POINTERPOS 

"timer" IECLASS TIMER 



"newprefs" IECLASS_NEWPREFS 
"diskremoved" IECLASS_DISKREMOVED 
"diskinserted" IECLASS_DISKINSERTED 

Qualifier is one of the qualifier strings from the table below. Each string corresponds to an input event qualifier as 
defined in <devices/inputevent.h>). A dash preceding the qualifier string tells the filter object not to care if that 
qualifier is present in the input event. Notice that there can be more than one qualifier (or none at all) in the input 
description string. 

Qualifier String Input Event Class 

"lshift" IEQUALIFIER_LSHIFT 

"rshift" IEQUALIFIER_RSHIFT 

"capslock" IEQUALIFIER_CAPSLOCK 

"control" IEQUALIFIER_CONTROL 

"lalt" IEQUALIFIER_LALT 

"rait" IEQUALIFIER_RALT 

"lcommand" IEQUALIFIER_LCOMMAND 

"rcommand" IEQUALIFIER_RCOMMAND 

"numericpad" IEQUALIFIER_NUMERICPAD 

"repeat" IEQUALIFIER_REPEAT 

"midbutton" IEQUALIFIER_MIDBUTTON 

"rbutton" IEQUALIFIER_RBUTTON 

"leftbutton" IEQUALIFIER_LEFTBUTTON 

"relativemouse" IEQUALIFIER_RELATIVEMOUSE 
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Synonym is one of the synonym strings from the table below. These strings act as synonyms for groups of 
qualifiers. Each string corresponds to a synonym identifier as defined in <libraries/commodities.h> . A dash 
preceding the synonym string tells the filter object not to care if that synonym is present in the input event. Notice 
that there can be more than one synonym (or none at all) in the input description string. 

Synonym String Synonym Identifier 

"shift" IXSYM_SHIFT /* look for either shift key */ 

"caps" IXSYM_CAPS /* look for either shift key or capslock */ 

"alt" IXSYM_ALT /* look for either alt key */ 

Upstroke is the literal string "upstroke". If this string is absent, the filter considers only downstrokes. If it is 
present alone, the filter considers only upstrokes. If preceded by a dash, the filter considers both upstrokes and 
downstrokes. 

Highmap is one of the following strings: 

"space", "backspace", "tab", "enter", "return", "esc", "del", "up", "down", "right", 
"left", "fl", "f2", "f3", "f4", "f5", "f6", "f7", "f8", "f9", "flO", "help". 

ANSICode is a single character (for example 'a') that Commodities Exchange looks up in the system default 
keymap. 

Here are some example description strings. For function key F2 with the left Shift and either Alt key pressed, the 
input description string would be: 

"rawkey lshift alt f2" 

To specify the key that produces an 'a' (this may or may not be the A key depending on the keymap), with or 
without any Shift, Alt, or control keys pressed use: 

"-shift -alt -control a" 
For a mouse move with the right mouse button down, use: 

"rawmouse rbutton" 
To specify a timer event use: 



'timer" 



Connecting CxObjects 



CxObj 


*headobj , 


CxObj 


*co) 


; 




CxObj 


*headobj , 


CxObj 


*co, 


CxObj 


*co pred 


CxObj 


*headobj , 


CxObj 


*co 


) ; 




CxObj 


*co, long 


pri ) , 








CxObj 


*co ) ; 











A CxObject has to be inserted into the Commodities network before it can process any CxMessages. 
AttachCxObj() adds a CxObject to the personal list of another CxObject. The HotKey.c example uses it to 
attach its filter to a broker. 

void AttachCxObj 
void InsertCxObj 
void EnqueueCxObj 
void SetCxObjPri 
void RemoveCxObj 

AttachCxObj() adds the CxObject to the end of headobj's personal list. The ordering of a CxObject list 
determines which object gets CxMessages first. InsertCxObjO also inserts a CxObject, but it inserts it after 
another CxObject already in the personal list (co_pred in the prototype above). 
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Brokers aren't the only CxObjects with a priority. All CxObjects have a priority associated with them. To change 
the priority of any CxObject, use the SetCxObjPriQ function. A commodity can use the priority to keep 
CxObjects in a personal list sorted by their priority. The commodities. library function EnqueueCxObj() inserts a 
CxObject into another CxObject's personal list based on priority. 

Like its name implies, the RemoveCxObj() function removes a CxObject from a personal list. Note that it is not 
necessary to remove a CxObject from a list in order to delete it. 

;/* HotKey.c - Simple hot key commodity compiled with SASC 5.10 

LC -bO -cfist -v - j 73 hotkey. c 

Blink FROM LIB : c . o, hotkey . o TO hotkey LIBRARY LIB : LC . lib, LIB : Amiga . lib 

quit 

*/ 
#include <exec/libraries . h> 
#include <libraries/commodities . h> 
#include <dos/dos.h> 
#include <clib/exec_protos . h> 
#include <clib/alib_protos . h> 
#include <clib/alib_stdio_protos . h> 
#include <clib/commodities_jprotos . h> 

#ifdef LATTICE 

int CXBRK(void) { return(O); } /* Disable Lattice CTRL/C handling */ 

int chkabort (void) { return(O); } 

#endif 

#define EVT_HOTKEY 1L 

void main (int, char **) ; 
void ProcessMsg (void) ; 

struct Library *CxBase, *IconBase; 

struct MsgPort *broker_mp; 

CxObj *broker, *filter, *sender, *translate; 

struct NewBroker newbroker = { 
NB_VERSION, 

"RKM HotKey" , /* string to identify this broker */ 

"A Simple HotKey", 
"A simple hot key commodity", 

NBU_UNIQUE | NBU_NOTIFY, /* Don't want any new commodities starting with this name. */ 
0, 0, 0, /* If someone tries it, let me know */ 

}; 

ULONG cxsigflag; 

void main (int argc, char **argv) 
{ 



UBYTE *hotkey, **ttypes; 
CxMsg *msg; 

if (CxBase = OpenLibrary ( "commodities . library" , 37L) ) 

{ 

/* open the icon. library for the support library */ 
/* functions, ArgArraylnit ( ) and ArgArrayDone ( ) */ 
if (IconBase = OpenLibrary ( "icon. library" , 36L) ) 

{ 

if (broker_mp = CreateMsgPort () ) 



{ 



newbroker .nb_Port = broker_mp; 
cxsigflag = 1L << broker_mp->mp_SigBit ; 

/* ArgArraylnit ( ) is a support library function (from the 2.0 version 

* of amiga.lib) that makes it easy to read arguments from either a 

* CLI or from Workbench's ToolTypes . Because it uses icon. library, 

* the library has to be open before calling this function. 

* ArgArrayDone ( ) cleans up after this function. 

*/ 

ttypes = ArgArraylnit (argc, argv) ; 

/* ArglntO (also from amiga.lib) searches through the array set up 

* by ArgArraylnit ( ) for a specific ToolType. If it finds one, it 

* returns the numeric value of the number that followed the 

* ToolType (i.e., CX_PRI0RITY=7) . If it doesn't find the ToolType, 

* it returns the default value (the third argument) 

*/ 

newbroker. nb_Pri = (BYTE) Arglnt (ttypes , "CX_PRIORITY" , 0); 

/* ArgStringO works just like ArglntO , except it returns a pointer to a string 

* rather than an integer. In the example below, if there is no ToolType 

* "HOTKEY", the function returns a pointer to "rawkey control esc". 

*/ 

hotkey = ArgString (ttypes, "HOTKEY", "rawkey control esc"); 

if (broker = CxBroker (&newbroker , NULL)) 

{ 

/* CxFilterO is a macro that creates a filter CxObject. This filter 
* passes input events that match the string pointed to by hotkey. 

*/ 

if (filter = CxFilter (hotkey) ) 

{ 

/* Add a CxObject to another's personal list */ 
AttachCxObj (broker, filter) ; 

/* CxSenderO creates a sender CxObject. Every time a sender gets 

* a CxMessage, it sends a new CxMessage to the port pointed to in 

* the first argument. CxSenderO 's second argument will be the ID 

* of any CxMessages the sender sends to the port. The data pointer 

* associated with the CxMessage will point to a *COPY* of the 

* InputEvent structure associated with the orginal CxMessage. 

*/ 

if (sender = CxSender (broker_mp, EVT_HOTKEY) ) 



{ 



AttachCxObj (filter, sender) ; 

/* CxTranslate ( ) creates a translate CxObject. When a translate 

* CxObject gets a CxMessage, it deletes the original CxMessage 

* and adds a new input event to the input .device' s input stream 

* after the Commodities input handler. CxTranslate' s argument 

* points to an InputEvent structure from which to create the new 

* input event. In this example, the pointer is NULL, meaning no 

* new event should be introduced, which causes any event that 

* reaches this object to disappear from the input stream. 

*/ 

if (translate = (CxTranslate (NULL) ) ) 

{ 

AttachCxObj (filter, translate) ; 

/* CxObj Error () is a commodities . library function that returns 
* the internal accumulated error code of a CxObject. 



*/ 

if (! CxObjError (filter) ) 

{ 

ActivateCxObj (broker, 1L) ; 
ProcessMsg ( ) ; 
} 
} 
} 
} 
/* DeleteCxObjAll ( ) is a commodities . library function that not only 

* deletes the CxObject pointed to in its argument, but it deletes 

* all of the CxObjects that are attached to it. 

*/ 

DeleteCxObjAll (broker) ; 

/* Empty the port of all CxMsgs */ 
while (msg = (CxMsg *) GetMsg (broker_mp) ) 
ReplyMsg ( (struct Message *)msg); 

} 

DeletePort (broker_mp) ; 

} 

/* this amiga.lib function cleans up after ArgArraylnit ( ) */ 
ArgArrayDone ( ) ; 
CloseLibrary (IconBase) ; 

} 

CloseLibrary (CxBase) ; 

} 
} 

void ProcessMsg (void) 

{ 

extern struct MsgPort *broker_mp; 

extern CxObj *broker; 

extern ULONG cxsigflag; 

CxMsg *msg; 

ULONG sigrcvd, msgid, msgtype; 

LONG returnvalue = 1L; 

while (returnvalue) 

{ 

sigrcvd = Wait (SIGBREAKF_CTRL_C | cxsigflag); 

while (msg = (CxMsg *) GetMsg (broker_mp) ) 

{ 

msgid = CxMsglD(msg) ; 
msgtype = CxMsgType (msg) ; 
ReplyMsg ( (struct Message *)msg); 

switch (msgtype) 

{ 

case CXM_IEVENT: 

printf ("A CXM_EVENT, "); 
switch (msgid) 

{ 

case EVT_HOTKEY: /* We got the message from the sender CxObject */ 

printf ("You hit the HotKey . \n" ) ; 

break; 
default : 

printf ( "unknown. \n" ) ; 

break; 

} 

break; 
case CXM_COMMAND: 

printf ("A command: "); 
switch (msgid) 

{ 

case CXCMDJDISABLE: 

printf ( "CXCMD_DISABLE\n" ) ; 

ActivateCxObj (broker, OL) ; 

break; 
case CXCMD_ENABLE : 

printf ( "CXCMD_ENABLE\n" ) ; 

ActivateCxObj (broker, 1L) ; 



break; 
case CXCMD_KILL: 

printf ( "CXCMD_KILL\n" ) ; 

returnvalue = OL; 

break; 
case CXCMD__UNIQUE : 
/* Commodities Exchange can be told not only to refuse to launch a 

* commodity with a name already in use but also can notify the 

* already running commodity that it happened. It does this by 

* sending a CXM_COMMAND with the ID set to CXMCMD_UNIQUE . If the 

* user tries to run a windowless commodity that is already running, 

* the user wants the commodity to shut down. */ 

printf ( "CXCMD_UNIQUE\n" ) ; 
returnvalue = OL; 
break; 
default : 

printf ( "Unknown msgid\n"); 
break; 

} 

break; 
default : 

printf ( "Unknown msgtype\n"); 
break; 
} 
} 
if (sigrcvd & SIGBREAKF_CTRL_C) 

{ 

returnvalue = OL; 

printf ("CTRL C signal break\n" ); 
} 
} 
} 
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Sender CxObjects 

A filter CxObject by itself is not especially useful. It needs some other CxObjects attached to it. A commodity 
interested in knowing if a specific key was pressed uses a filter to detect and divert the corresponding 
CxMessage down the filter's personal list. The filter does this without letting the commodity know what 
happened. The sender CxObject can be attached to a filter to notify a commodity that it received a CxMessage. 
CxSender() is a macro that creates a sender CxObject. 

senderCxObj = CxObj *CxSender (struct MsgPort *senderport , LONG cxmID) ; 

CxSenderQ supplies the sender with an Exec message port and an ID. For every CxMessage a sender 
receives, it sends a new CxMessage to the Exec message port passed in CxSender(). Normally, the commodity 
creates this port. It is not unusual for a commodity's broker and sender(s) to share an Exec message port. The 
HotKey.c example does this to avoid creating unnecessary message ports. A sender uses the ID (cxmID) passed 
to CxSenderQ as the ID for all the CxMessages that the it transmits. A commodity uses the ID to monitor 
CxMessages from several senders at a single message port. 

A sender does several things when it receives a CxMessage. First, it duplicates the CxMessages 
corresponding input event and creates a new CxMessage. Then, it points the new CxMessages data field to the 
copy of the input event and sets the new CxMessage's ID to the ID passed to CxSender(). Finally, it sends the 
new CxMessage to the port passed to CxSender(), asynchronously. 

Because HotKey uses only one message port between its broker and sender object, it has to extract the 
CxMessage's type so it can tell if it is a CXMJEVENT or a CXM_COMMAND. If HotKey gets a CXMJEVENT, it 
compares the CxMessage's ID to the sender's ID, EVT_HOTKEY, to see which sender sent the CxMessage. Of 
course HotKey has only one sender, so it only checks for only one ID. If it had more senders, HotKey would 
check for the ID of each of the other senders as well. 

Although HotKey doesn't use it, a CXMJEVENT CxMessage contains a pointer to the copy of an input event. A 
commodity can extract this pointer ( using CxMsgDataQ ) if it needs to examine the input event copy. This 
pointer is only valid before the CxMessage reply. Note that it does not make any sense to modify the input event 
copy. 



Senders are attached almost exclusively to CxObjects that filter out most input events (usually a filter CxObject). 
Because a sender sends a CxMessage for every single input event it gets, it should only get a select few input 
events. The AttachCxObjQ function can add a CxObject to the end of a filter's (or some other filtering 
CxObject's) personal list. A commodity should not attach a CxObject to a sender as a sender ignores any 
CxObjects in its personal list. 



Translate CxObjects 



Normally, after a commodity processes a hot key input event, it needs to eliminate that input event. Other 
commodities may need to replace an input event with a different one. The translate CxObject can be used for 
these purposes. 

translateCxObj = CxObj *CxTranslate (struct InputEvent *newinputevent) ; 

The macro CxTranslateQ creates a new translate CxObject. CxTranslate()'s only argument is a pointer to a 
chain of one or more InputEvent structures. 
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When a translate CxObject receives a CxMessage, it eliminates the CxMessage and its corresponding input 
event from the system. The translator introduces a new input event, which Commodities Exchange copies from 
the InputEvent structure passed to CxTranslate() (newinputevent from the function prototype above), in place of 
the deleted input event. 

A translator is normally attached to some kind of filtering CxObject. If it wasn't, it would translate all input events 
into the same exact input event. Like the sender CxObject, a translator does not divert CxMessages down its 
personal list, so it doesn't serve any purpose to add any to it. 

void SetTranslate ( CxObj *translator, struct InputEvent *ie ); 

It is possible to change the InputEvent structure that a translator looks at when it creates and introduces new 
input events into the input stream. The function SetTranslate() accepts a pointer to the new InputEvent 
structure, which the translator will duplicate and introduce when it receives a CxMessage. 

HotKey utilizes a special kind of translator. Instead of supplying a new input event, HotKey passes a NULL to 
CxTranslate(). If a translator has a NULL new input event pointer, it does not introduce a new input event, but 
still eliminates any CxMessages and corresponding input events it receives. 



CxObject Errors 



A Commodities Exchange function that acts on a CxObject records errors in the CxObject's accumulated error 
field. The function CxObjError() returns a CxObject's error field. 

co_errorf ield = LONG CxObjError( CxObj *co ) ; 

Each bit in the error field corresponds to a specific type of error. The following is a list of the currently defined 
CxObject errors and their corresponding bit mask constants. 

Error Constant Meaning 

COERRJSNULL CxObjError() was passed a NULL. 

COERR_NULLATTACH Someone tried to attach a NULL CxObject to this CxObject. 
COERR_BADFILTER This filter CxObject currently has an invalid filter description. 
COERR_BADTYPE Someone tried to perform a type specific function on the wrong type of 

CxObject (for example calling SetFilter() on a sender CxObject). 

The remaining bits are reserved by Commodore for future use. HotKey. c checks the error field of its filter 
CxObject to make sure the filter is valid. HotKey.c does not need to check the other objects with CxObjError() 
because it already makes sure that these other objects are not NULL, which is the only other kind of error the 
other objects can cause in this situation. 

Commodities Exchange has a function that clears a CxObject's accumulated error field, ClearCxObjError(). 



void ClearCxObj Error ( CxObj *co ); 

A commodity should be careful about using this, especially on a filter. If a commodity clears a filter's error field 
and the COERR_BADFILTER bit is set, Commodities Exchange will think that the filter is OK and start sending 
messages through it. 

742 Amiga ROM Kernel Reference Manual: Libraries 

Uniqueness 

When a commodity opens its broker, it can ask Commodities Exchange not to launch another broker with the 
same name (nb_Name). The purpose of the uniqueness feature is to prevent the user from starting duplicate 
commodities. If a commodity asks, Commodities Exchange will not only refuse to create a new, similarly named 
broker, but it will also notify the original commodity if someone tries to do so. 

A commodity tells Commodities Exchange not to allow duplicates by setting certain bits in the nb_Unique field of 
the NewBroker structure it sends to CxBroker(): 

NBUJJNIQUE bit 
NBU_NOTIFY bit 1 

Setting the NBUJJNIQUE bit prevents duplicate commodities. Setting the NBU_NOTIFY bit tells Commodities 
Exchange to notify a commodity if an attempt was made to launch a duplicate. Such a commodity will receive a 
CXM_COMMAND CxMessage with an ID of CXCMDJJNIQUE when someone tries to duplicate it. Because the 
uniqueness feature uses the name a programmer gives a commodity to differentiate it from other commodities, it 
is possible for completely different commodities to share the same name, preventing the two from coexisting. For 
this reason, a commodity should not use a name that is likely to be in use by other commodities (like "filter" or 
"hotkey"). Instead, use a name that matches the commodity name. 

When HotKey.c gets a CXCMDUNIQUE CxMessage, it shuts itself down. HotKey.c and all the windowless 
commodities that come with the Release 2 Workbench shut themselves down when they get a CXCMD_UNIQUE 
CxMessage. Because the user will expect all windowless commodities to work this way, all windowless 
commodities should follow this standard. 

When the user tries to launch a duplicate of a system commodity that has a window, the system commodity 
moves its window to the front of the display, as if the user had clicked the "Show" gadget in the controller 
program's window. A windowed commodity should mimic conventions set by existing windowed system 
commodities, and move its window to the front of the display. 



Signal CxObjects 



A commodity can use a sender CxObject to find out if a CxMessage has "visited" a CxObject, but this method 
unnecessarily uses system resources. A commodity that is only interested in knowing if such a visitation took 
place does not need to see a corresponding input event or a CxMessage ID. Instead, Commodities Exchange 
has a CxObject that uses an Exec signal. 

signalCxObj = CxObj *CxSignal (struct Task *, LONG cx_signal) ; 

CxSignalQ sets up a signal CxObject. When a signal CxObject receives a CxMessage, it signals a task. The 
commodity is responsible for determining the proper task ID and allocating the signal. Normally, a commodity 
wants to be signalled so it uses FindTask(NULL) to find it's own task address. Note that cx_signal from the 
above prototype is the signal number as returned by AllocSignal(), not the signal mask made from that number. 
For more information on signals, see the "Exec Signals" chapter. 

The example Divert.c (shown a little later in this chapter) uses a signal CxObject. 
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Custom CxObjects 

Although the CxObjects mentioned so far take care of most of the input event handling a commodity needs to do, 



they cannot do it all. This is why Commodities Exchange has a custom CxObject. When a custom CxObject 
receives a CxMessage, it calls a function provided by the commodity. 

customCxObj = CxObj *CxCustom (LONG *customf unction () , LONG cxmID) ; 

A custom CxObject is the only means by which a commodity can directly modify input events as they pass 
through the Commodities network as CxMessages. For this reason, it is probably the most dangerous of the 
CxObjects to use. 

A Warning About Custom CxObjects. Unlike the rest of the code a commodities programmer 
writes, the code passed to a custom CxObject runs as part of the input.device task, putting 
severe restrictions on the function. No DOS or Intuition functions can be called. No 
assumptions can be made about the values of registers upon entry. Any function passed to 
CxCustom() should be very quick and very simple, with a minimum of stack usage. 

Commodities Exchange calls a custom CxObject's function as follows: 

void customf unction (CxMsg *cxm, CxObj *customcxobj ) ; 

where cxm is a pointer to a CxMessage corresponding to a real input event, and customcxobj is a pointer to the 
custom CxObject. The custom function can extract the pointer to the input event by calling CxMsgDataQ. 
Before passing the CxMessage to the custom function, Commodities Exchange sets the CxMessage's ID to the 
ID passed to CxCustom(). 

The following is an example of a custom CxObject function that swaps the function of the left and right mouse 
buttons. 

custom = CxCustom (CxFunction, OL) 

/* The custom function for the custom CxObject. Any code for a */ 
/* custom CxObj must be short and sweet. This code runs as part */ 
/* of the input.device task */ 

#define CODEMASK (OxOOFF & IECODE_LBUTTON & IECODE_RBUTTON) 
void CxFunction (register CxMsg *cxm, CxObj *co) 

{ 

struct InputEvent *ie; 
UWORD mousequals = 0x0000; 

/* Get the struct InputEvent associated with this CxMsg. Unlike 

* the InputEvent extracted from a CxSender's CxMsg, this is a 

* *REAL* input event, be careful with it. */ 
ie = (struct InputEvent *) CxMsgData (cxm) ; 

/* Check to see if this input event is a left or right mouse button 

* by itself (a mouse button can also be a qualifier) . If it is, 

* flip the low order bit to switch leftbutton <--> rightbutton. */ 
if (ie->ie_Class == IECLASS_RAWMOUSE) 

if ( (ie->ie_Code & CODEMASK) == CODEMASK) ie->ie_Code A = 0x0001; 

/* Check the qualifiers. If a mouse button was down when this */ 

/* input event occurred, set the other mouse button bit. */ 

if (ie->ie_Qualif ier & IEQUALIFIER_RBUTTON) mousequals |= IEQUALIFIER_LEFTBUTTON; 

if (ie->ie_Qualif ier & IEQUALIFIER_LEFTBUTTON) mousequals |= IEQUALIFIER_RBUTTON; 

/* clear the RBUTTON and LEFTBUTTON qualifier bits */ 

ie->ie_Qualif ier &= ~ (IEQUALIFIER_LEFTBUTTON | IEQUALIFIER_RBUTTON) ; 

/* set the mouse button qualifier bits to their new values */ 
ie->ie_Qualif ier |= mousequals; } 
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Debug CxObjects 

The final CxObject is the debug CxObject. When a debug CxObject receives a CxMessage, it sends 
debugging information to the serial port using kprintf(). 



debugCxObj = CxObj *CxDebug (LONG ID); 

The debug CxObject will kprintf() the following information about itself, the CxMsg, and the corresponding 
InputEvent structure: 

DEBUG NODE: 7CB5AB0 , ID: 2 

CxMsg: 7CA6EF2, type: 0, data 2007CA destination 6F1E07CB 

dump IE: 7CA6F1E 

Class 1 

Code 4 

Qualifier 8000 

EventAddress 40001802 

There has to be a terminal connected to the Amiga's serial port to receive this information. See the kprintf() 
Autodoc (debug. lib) for more details. Note that the debug CxObject did not work before V37. 



The IX Structure 



Commodities Exchange does not use the input event description strings discussed earlier to match input events. 
Instead, Commodities Exchange converts these strings to its own internal format. These input expressions are 
available for commodities to use instead of the input description strings. The following is the IX structure as 
defined in <libraries/commodities.h>: 

#define IX_VERSION 2 

struct InputXpression { 

UBYTE ixJVersion; /* must be set to IX_VERSION */ 

UBYTE ix_Class; /* class must match exactly */ 

UWORD ix_Code ; 

UWORD ix_CodeMask; /* normally used for UPCODE */ 

UWORD ix_Qualif ier; 

UWORD ix_QualMask; 

UWORD ix_QualSame; /* synonyms in qualifier */ 

}; 

typedef struct InputXpression IX; 

The ix_Version field contains the current version number of the InputXpression structure. The current version is 
defined as IX_VERSION. The ix_Class field contains the I ECLASS_ constant (defined in <devices/inputevent.h>) 
of the class of input event sought. Commodities Exchange uses the ix_Code and ix_CodeMask fields to match 
the ie_Code field of a struct InputEvent. The bits of ix_CodeMask indicate which bits are relevant in the 
ixCode field when trying to match against a ie_Code. If any bits in ix CodeMask are off, Commodities 
Exchange does not consider the corresponding bit in ie_Code when trying to match input events. This is used 
primarily to mask out the IECODE_UP_PREFIX bit of rawkey events, making it easier to match both up and down 
presses of a particular key. 

IX's qualifier fields, ix_Qualifier, ixQualMask, and ixQualSame, are used to match the ie_Qualifier field of an 
InputEvent structure. The ix_Qualifier and ix QualMask fields work just like ix_Code and ix_CodeMask. The 
bits of ixQualMask indicate which bits are relevant when comparing ix Qualifier to ie Qualifier. The 
ix_QualSame field tells Commodities Exchange that certain qualifiers are equivalent: 

#define IXSYM_SHIFT 1 /* left- and right- shift are equivalent */ 
#define IXSYM_CAPS 2 /* either shift or caps lock are equivalent */ 
#define IXSYM_ALT 4 /* left- and right- alt are equivalent */ 
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For example, the input description string 

"rawkey -caps -lalt -relativemouse -upstroke rait tab" 

matches a tab upstroke or downstroke with the right Alt key pressed whether or not the left Alt, either Shift, or the 
Caps Lock keys are down. The following IX structure corresponds to that input description string: 



IX ix = { 

IX_VERSION, /* The version */ 

IECLASS_RAWKEY, /* We're looking for a RAWKEY event */ 

0x42, /* The key the usaO keymap maps to a tab */ 

OxOOFF & (~IECODE_UP_PREFIX) , /* We want up and down key presses */ 
IEQUALIFIER_RALT, /* The right alt key must be down */ 

OxFFFF & ~(IEQUALIFIER_LALT | IEQUALIFIER_LSHIFT 

IEQUALIFIER_RSHIFT | IEQUALIFIER_CAPSLOCK [ 
IEQUALIFIER_RELATIVEMOUSE) , 
/* don't care about left alt, shift, capslock, or relativemouse qualifiers */ 
IXSYM_CAPS /* The shift keys and the capslock key */ 
/* qualifiers are all equivalent */ 

}; 

The CxFilter() macro only accepts a description string to describe an input event. A commodity can change this 
filter, however, with the SetFilter() and SetFilterlX() function calls. 

void SetFilter( CxObj *filter, UBYTE *descrstring ) ; 
void SetFilterIX( CxObj *filter, IX *ix ); 

SetFilter() and SetFilterlX() change which input events a filter CxObject diverts. SetFilter() accepts a pointer to 
an input description string. SetFilterlX() accepts a pointer to an IX input expression. A commodity that uses 
either of these functions should check the filter's error code with CxObjError() to make sure the change worked. 

The function ParselX() parses an input description string and translates it into an IX input expression. 

errorcode = LONG ParselX ( UBYTE *descrstring, IX *ix ) ; 

Commodities Exchange uses ParselX() to convert the description string in CxFilter() to an IX input expression. As 
was mentioned previously, as of commodities. library version 37.3, ParselX() does not work with certain kinds of 
input strings. 



Controlling CxMessages 



A Custom CxObject has the power to directly manipulate the CxMessages that travel around the Commodities 
network. One way is to directly change values in the corresponding input event. Another way is to redirect (or 
dispose of) the CxMessages. 

void DivertCxMsg ( CxMsg *cxm, CxObj *headobj , CxObj *retobj ) ; 
void RouteCxMsg ( CxMsg *cxm, CxObj *co ) ; 
void DisposeCxMsg ( CxMsg *cxm ) ; 

DivertCxMsg() and RouteCxMsgQ dictate where the CxMessage will go next. Conceptually, DivertCxMsgQ is 
analogous to a subroutine in a program; the CxMessage will travel down the personal list of a CxObject 
(headobj in the prototype) until it gets to the end of that list. It then returns and visits the CxObject that follows 
the return CxObject (the return CxObject in the prototype above is retobj). RouteCxMsg() is analogous to a 
goto in a program; it has no CxObject to return to. 

DisposeCxMsg() removes a CxMessage from the network and releases its resources. The translate CxObject 
uses this function to remove a CxMessage. 
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The example Divert. c shows how to use DivertCxMsg() as well as a signal CxObject. 

;/* divert. c - commodity to monitor user inactivity - compiled with SASC 5.10 

LC -bO -cfist -v -j73 divert . c 

Blink FROM LIB : c . o, divert . o TO divert LIBRARY LIB : LC . lib, LIB : Amiga . lib NODEBUG SC SD 

quit; */ 

#include <exec/libraries .h> 

#include <libraries/commodities .h> 

#include <dos/dos.h> 

#include <clib/exec_protos .h> 

#include <clib/alib_protos .h> 



#include <clib/alib_stdio_protos . h> 
#include <clib/commodities _protos . h> 
#include <devices/inputevent . h> 

#ifdef LATTICE 

int CXBRK(void) { return(O); } /* Disable Lattice CTRL/C handling */ 

int chkabort (void) { return(O); } 

#endif 

#define TIMERJCLICKS 100 

void main (int, char **) ; 

void ProcessMsg (void) ; 

void CxFunction (CxMsg *, CxObj *) ; 

struct Library *CxBase, *IconBase; 

struct MsgPort *broker_mp; 

CxObj *broker, *cocustom, *cosignal; 

struct NewBroker newbroker = 

{ 

NBJVERSION, 

"Divert", /* string to identify this broker */ 

"Divert" , 

"show divert", 

NBU_UNIQUE | NBU_NOTIFY, /* Don't want any new commodities starting with this name. */ 

0, 0, 0, /* If someone tries it, let me know */ 

}; 

struct Task *task; 

ULONG cxsigflag, signal, cxobj signal ; 

void main (int argc, char **argv) 

{ 

UBYTE **ttypes; 
CxMsg *msg; 

if (CxBase = OpenLibrary ( "commodities . library" , 37L) ) 

{ 

/* open the icon. library for support library functions, ArgArraylnit ( ) and ArgArrayDone ( ) */ 
if (IconBase = OpenLibrary ( "icon. library" , 36L) ) 

{ 

if (broker_mp = CreateMsgPort ( ) ) 

{ 

newbroker .nb_Port = broker_mp; 
cxsigflag = 1L << broker_mp->mp_SigBit ; 

/* ArgArraylnit ( ) is a support library function (in the 2.0 version of amiga.lib) */ 

/* that makes it easy to read arguments from either a CLI or from Workbench's */ 

/* ToolTypes . Because it uses icon. library, the library has to be open before */ 

/* before calling this function. ArgArrayDone ( ) cleans up after this function. */ 
ttypes = ArgArraylnit (argc, argv) ; 

/* ArglntO (in amiga.lib) searches through the array set up by ArgArraylnit ( ) */ 

/* for a specific ToolType. If it finds one, it returns the numeric value of the */ 

/* number that followed the ToolType (i.e., CX_PRIORITY=7) . If it doesn't find */ 

/* the ToolType, it returns the default value (the third argument) */ 
newbroker. nb_Pri = (BYTE) Arglnt (ttypes , "CX_PRIORITY" , 0); 

if (broker = CxBroker (&newbroker , NULL)) 

{ 
/* CxCustomO takes two arguments, a pointer to the custom function */ 

/* and an ID. Commodities Exchange will assign that ID to any CxMsg */ 

/* passed to the custom function. */ 

if (cocustom = CxCustom (CxFunction, 0L) ) 



/ 



{ 



AttachCxObj (broker, cocustom) ; 

/* Allocate a signal bit for the signal CxObj */ 
if ( (signal = (ULONG) AllocSignal ( -1L) ) != -1) 

{ 

/* set up the signal mask */ 



cxobj signal = 1L << signal; 
cxsigflag |= cxobj signal; 

/* CxSignal takes two arguments, a pointer to the task to signal */ 
/* (normally the commodity) and the number of the signal bit the */ 
/* commodity acquired to signal with. */ 

task = FindTask(NULL) ; 

if (cosignal = CxSignal (task, signal)) 

{ 

AttachCxObj (cocustom, cosignal) ; 
ActivateCxObj (broker, 1L) ; 
ProcessMsg ( ) ; 

} 

FreeSignal (signal) ; 

} 

} 
/* DeleteCxObjAll ( ) is a commodities . library function that not only deletes */ 
/* the CxObject pointed to in its argument, but it deletes all of the */ 

/* CxObjects that are attached to it. */ 

DeleteCxObjAll (broker) ; 

/* Empty the port of all CxMsgs */ 
while (msg = (CxMsg *) GetMsg (broker_mp) ) 
ReplyMsg ( (struct Message *)msg); 

} 

DeletePort (broker__mp) ; 

} 
ArgArrayDone ( ) ; /* this amiga.lib function cleans up after ArgArraylnit ( ) */ 

CloseLibrary (IconBase) ; 

} 

CloseLibrary (CxBase) ; 

} 
} 

void ProcessMsg (void) 

{ 

extern struct MsgPort *broker_mp; 

extern CxObj *broker; 

extern ULONG cxsigflag; 

CxMsg *msg; 

ULONG sigrcvd, msgid; 

LONG returnvalue = 1L; 

while (returnvalue) 

{ 

sigrcvd = Wait (SIGBREAKF_CTRL_C | cxsigflag); 

while (msg = (CxMsg *) GetMsg (broker_mp) ) 

{ 

msgid = CxMsglD(msg) ; 

ReplyMsg ( (struct Message *)msg); 

switch (msgid) 

{ 

case CXCMD_DISABLE: 

ActivateCxObj (broker, OL) ; 

break; 
case CXCMD_ENABLE : 

ActivateCxObj (broker, 1L) ; 

break; 
case CXCMD_KILL: 

returnvalue = OL; 

break; 
case CXCMD_UNIQUE : 

returnvalue = OL; 

break; 
} 
} 

if (sigrcvd & SIGBREAKF_CTRL_C) returnvalue = OL; 
/* Check to see if the signal CxObj signalled us. */ 



if (sigrcvd & cxobjsignal) printff'Got Signal\n"); 
} 
} 

/* The custom function for the custom CxObject. Any code for a custom CxObj must be short */ 
/* and sweet because it runs as part of the input. device task. */ 

void CxFunction (register CxMsg *cxm, CxObj *co) 

{ 

struct InputEvent *ie; 
static ULONG time = OL; 

/* Get the struct InputEvent associated with this CxMsg. Unlike the InputEvent */ 

/* extracted from a CxSender's CxMsg, this is a *REAL* input event, be careful with it. */ 
ie = (struct InputEvent *) CxMsgData (cxm) ; 

/* This custom function counts the number of timer events that go by while no other input*/ 
/* events occur. If it counts more than a certain amount of timer events, it clears the*/ 
/* count and diverts the timer event CxMsg to the custom object's personal */ 

/* list. If an event besides a timer event passes by, the timer event count is reset. */ 
if (ie->ie_Class == IECLASS_TIMER) 

{ 

time++ ; 

if (time >= TIMER_CLICKS) 

{ 

time = OL; 

DivertCxMsg (cxm, co, co) ; 
} 
} 
else 

time = OL; 
} 

New Input Events 

Commodities Exchange also has functions used to introduce new input events to the input stream. 

struct InputEvent *InvertString ( UBYTE *string, ULONG *keymap ) ; 
void FreelEvents ( struct InputEvent *ie ); 

void AddlEvents ( struct InputEvent *ie ); 

InvertStringQ is an amiga.lib function that accepts an ASCII string and creates a linked list of input events that 
translate into the string using the supplied keymap (or the system default if the key map is NULL). The NULL 
terminated string may contain ANSI character codes, an input description enclosed in angle (<>) brackets, or one 
of the following backslash escape characters: 

\r -- return 

\t -- tab 

\\ -- backslash 

For example: 

abc<alt fl>\rhi there. 

FreelEvents() frees a list of input events allocated by InvertStringQ. AddlEventsQ is a commodities. library 
function that adds a linked list of input events at the the top of the Commodities network. Each input event in the 
list is made into an individual CxMessage. Note that if passed a linked list of input events created by 
lnvertString(), the order the events appear in the string will be reversed. 
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;/* PopShell.c - Simple hot key commodity compiled with SASC 5.10 

LC -bO -cfist -v - j 73 popshell.c 

Blink FROM LIB : c . o, popshell . o TO popshell LIBRARY LIB : LC . lib, LIB : Amiga . lib 

quit 

*/ 

#include <exec/libraries . h> 
#include <libraries/commodities . h> 
#include <dos/dos.h> 



#include <clib/exec_protos . h> 
#include <clib/alib_protos . h> 
#include <clib/alib_stdio_protos . h> 
#include <clib/commodities _protos . h> 

#ifdef LATTICE 

int CXBRK(void) { return(O); } /* Disable Lattice CTRL/C handling */ 

int chkabort (void) { return(O); } 

#endif 

void main (int, char **) ; 
void ProcessMsg (void) ; 

#define EVT_HOTKEY 1L 

struct Library *CxBase, *IconBase; 

struct MsgPort *broker_mp; 

CxObj *broker, *filter, *sender, *translate; 

struct NewBroker newbroker = 

{ 

NB_VERSION, 

"RKM PopShell", /* string to identify this broker */ 

"A Simple PopShell", 

"A simple PopShell commodity", 

NBU_UNIQUE | NBU_NOTIFY, /* Don't want any new commodities starting with this name. */ 

0, 0, 0, /* If someone tries it, let me know */ 

}; 

UBYTE *newshell = " \rllehswen" ; /* "newshell" spelled backwards */ 
struct InputEvent *ie; 
ULONG cxsigflag; 

void main (int argc, char **argv) 

{ 

UBYTE *hotkey, **ttypes; 
CxMsg *msg; 

if (CxBase = OpenLibrary ( "commodities . library" , 37L) ) 

{ 

if (IconBase = OpenLibrary ( "icon. library" , 36L) ) 

{ 

if (broker_mp - CreateMsgPort ( ) ) 

{ 

newbroker .nb_Port = broker_mp; 

cxsigflag = 1L << broker_mp->mp_SigBit ; 

ttypes = ArgArraylnit (argc, argv) ; 

newbroker. nb_Pri = (BYTE) Arglnt (ttypes , "CX_PRIORITY" , 0) ; 

hotkey = ArgString (ttypes, "HOTKEY", "rawkey control esc"); 

if (broker = CxBroker (&newbroker , NULL)) 

{ 

/* HotKeyO is an amiga.lib function that creates a filter, sender */ 
/* and translate CxObject and connects them to report a hot key */ 
/* press and delete its input event. */ 
if (filter = HotKey (hotkey, broker_mp, EVT_HOTKEY) ) 

{ 
AttachCxObj (broker, filter) ; /* Add a CxObject to another's personal list */ 

if (! CxObjError (filter) ) 

{ 

/* InvertString ( ) is an amiga.lib function that creates a linked */ 

/* list of input events which would translate into the string */ 

/* passed to it. Note that it puts the input events in the */ 

/* opposite order in which the corresponding letters appear in */ 

/* the string. A translate CxObject expects them backwards. */ 
if (ie = InvertString (newshell, NULL)) 

{ 

ActivateCxObj (broker, 1L) ; 
ProcessMsg ( ) ; 
/* we have to release the memory allocated by InvertString. */ 
FreelEvents (ie) ; 



} 

} 
} 

/* DeleteCxObjAll ( ) is a commodities . library function that not only */ 

/* deletes the CxObject pointed to in its argument, but deletes all of */ 

/* the CxObjects attached to it. */ 
DeleteCxObjAll (broker) ; 

/* Empty the port of all CxMsgs */ 
while (msg = (CxMsg *) GetMsg (broker_mp) ) 
ReplyMsg ( (struct Message *)msg); 

} 

DeletePort (broker__mp) ; 

} 

ArgArrayDone ( ) ; /* this amiga.lib function cleans up after ArgArraylnit ( ) */ 
CloseLibrary (IconBase) ; 

} 

CloseLibrary (CxBase) ; 



void ProcessMsg (void) 

{ 

extern struct MsgPort *broker_mp; 

extern CxObj *broker; 

extern ULONG cxsigflag; 

CxMsg *msg; 

ULONG sigrcvd, msgid, msgtype; 

LONG returnvalue = 1L; 

while (returnvalue) 

{ 

sigrcvd = Wait (SIGBREAKF_CTRL_C | cxsigflag); 

while (msg = (CxMsg *) GetMsg (broker_mp) ) 

{ 

msgid = CxMsgID (msg) ; 
msgtype = CxMsgType (msg) ; 
ReplyMsg ( (struct Message *)msg); 

switch (msgtype) 

{ 

case CXM_IEVENT: 

printf ("A CXM_EVENT, " ) ; 
switch (msgid) 

{ 

case EVT_HOTKEY: 

/* We got the message from the sender CxObject */ 
printf ("You hit the HotKey . \n" ) ; 
/* Add the string "newshell" to input * stream. If a shell */ 
/* gets it, it'll open a new shell. */ 

AddlEvents (ie) ; 
break; 
default : 

printf ( "unknown. \n" ) ; 
break; 

} 

break; 
case CXM_COMMAND: 

printf ("A command: "); 
switch (msgid) 

{ 

case CXCMDJDISABLE: 

printf ( "CXCMD_DISABLE\n" ) ; 

ActivateCxObj (broker, OL) ; 

break; 
case CXCMD_ENABLE : 

printf ( "CXCMD_ENABLE\n" ) ; 

ActivateCxObj (broker, 1L) ; 

break; 
case CXCMD_KILL: 

printf ( "CXCMD_KILL\n" ) ; 



returnvalue = OL; 

break; 
case CXCMD_UNIQUE : 
/* Commodities Exchange can be told not only to refuse to launch a */ 
/* commodity with a name already in use but also can notify the */ 
/* already running commodity that it happened. It does this by */ 
/* sending a CXM_COMMAND with the ID set to CXMCMD_UNIQUE . If the */ 
/* user tries to run a windowless commodity that is already running, */ 
/* the user wants the commodity to shut down. */ 

print f ( "CXCMD_UNIQUE\n" ) ; 

returnvalue = OL; 

break; 
default : 

printf ( "Unknown msgid\n"); 

break; 

} 

break; 
default : 

printf ( "Unknown msgtype\n"); 
break; 



if (sigrcvd & SIGBREAKF_CTRL_C) 

{ 

returnvalue = OL; 

printf ("CTRL C signal break\n" ); 
} 
} 
} 



Function Reference 



The following are brief descriptions of the Commodities Exchange functions covered in this chapter. All of these 
functions require Release 2 or a later version of the Amiga operating system. See the Amiga ROM Kernel 
Reference Manual: Includes and Autodocs for details on each function call. 

Table 31-2: Commodities Exchange Functions 



Function 



CxBfoReTfJ 

CxFilter() 

CxSender() 

CxTranslate() 

CxSignal() 

CxCustom() 

CxDebug() 

DeleteCxObjO 

DeleteCxObjAIIQ 



Description 

ureates a uxuoject or type 



BroKer. 

Filter. 

Sender. 

Translate. 

Signal. 

Custom. 

Debug. 



ActivateCxObjO 



Creates a CxObject of type 
Creates a CxObject of type : 
Creates a CxObject of type 
Creates a CxObject of type : 
Creates a CxObject of type > 
Creates a CxObject of type 
Frees a single CxObject 
Frees a group of connected CxObjects 



Activates a newly created CxObject in the commodities network. 

Sets up substitution of one input event for another by translate CxObjects. 



CxTranslate() 



CxMsg I ype() 
CxMsgData() 
CxMsglDQ 



hinds the type or a CxMessage. 
Returns the CxMessage data. 
Returns the CxMessage ID. 



CxObjError() 

ClearCxObjError() 

ArgArraylnit() 

ArgArrayDone() 

ArgString() 

ArglntQ 



Returns the CxObjects accumulated error field. 

Clear the CxObject's accumulated error field. 

ureate a I ool I ypes array from argc ana argv (Workbench or Shell). 

Free the resources used by ArgArraylnit(). 

Return the string associated with a given Tool Type in the array. 

Return the integer associated with a given Tool Type in the array. 



AttachCxObj() — 

lnsertCxObj() 

EnqueueCxObj() 

SetCxObjPri() 

RemoveCxObjQ 



Allaches a CxObject lo Ihe end of a given CxObject's list 
Inserts a CxObject in a given position in a CxObject's list. 
Inserts a CxObject in a CxObject's list by priority. 
Sets a CxObject's priority for EnqueueCxObj(). 
Removes a CxObject from a list. 



SetFilter() 
SetFilterlX() 
ParselXQ — 



Set a filter tor a CxObject from an input description string. 
Set a filter for a CxObject from an IX data structure. 



Convert an input description string to an IX data structure. 



UivertCxMsg() 
RouteCxMsg() 
DisposeCxMsgO 



Divert a CxMessage to one CxObject and return it to another. 

Redirect a CxMessage to a new CxObject. 

Cancel a CxMessage removing it from the Commodities network. 



invertbtrmgo ureates a linked list of input events that correspond to a given string. 

FreelEvents() Frees the linked list of input events created with lnvertString(). 

AddlEventsQ Converts a list of input events to CxMessages and puts them into the network. 
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Chapter 32 
Expansion Library 



Amiga RAM expansion boards and other expansion bus peripherals are designed to reside at dynamically 
assigned address spaces within the system. The configuration and initialization of these expansion peripherals is 
performed by the expansion. library. 



AUTOCONFIG™ 



The Amiga AUTOCONFIG protocol is designed to allow the dynamic assignment of available address space to 
expansion boards, eliminating the need for user configuration via jumpers. Such expansion boards include 
memory boards, hard disk controllers, network interfaces, and other special purpose expansion devices. Some 
expansion devices, such as RAM boards, require no special driver software. Other types of expansion devices 
may use a disk-loaded driver from the DEVS: or SYS:Expansion drawer, or an on-board ROM driver (for example, 
a self-booting hard disk controller). 

This chapter will concentrate on the software and driver side of Zorro expansion devices, using a Zorro II device 
as an example. Zorro III devices have additional identifying bits and memory size options which are described in 
the Zorro III hardware documentation. For more information on Zorro II and Zorro III expansion hardware, see the 
"Zorro Expansion Bus" appendix of the Amiga Hardware Reference Manual, 3rd Edition from Addison-Wesley. 
For additional information specific to Zorro II boards, see the Commodore publication A500/A2000 Technical 
Reference Manual. 

AUTOCONFIG occurs whenever the Amiga is powered on or reset. During early system initialization, 
expansion. library identifies the expansion boards that are installed in the Amiga and dynamically assigns an 
appropriate address range for each board to reside at. During this AUTOCONFIG process, each expansion board 
first appears in turn at $E80000 (Zorro II) or $FF000000 (Zorro III), presenting readable identification information, 
generally in a PAL or a ROM, at the beginning of the board. The identification includes the size of the board, its 
address space preferences, type of board (memory or other), and a unique Hardware Manufacturer Number 
assigned by Commodore Applications and Technical Support (CATS), West Chester, Pennsylvania. 
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The unique Hardware Manufacturer number, in combination with a vendor-supplied product number, provides a 
way for boards to be identified and for disk-based drivers to be matched with expansion boards. All expansion 
boards for the Amiga must implement the AUTOCONFIG protocol. 

Note: A unique Hardware Manufacturer number assigned by CATS is not the same as a 
Developer number. 



The Expansion Sequence 



During system initialization, expansion. library configures each expansion peripheral in turn by examining its 
identification information and assigning it an appropriate address space. If the board is a RAM board, it can be 
added to the system memory list to make the RAM available for allocation by system tasks. 

Descriptions of all configured boards are kept in a private ExpansionBase list of ConfigDev structures. A 
board's identification information is stored in the ExpansionRom sub-structure contained within the ConfigDev 
structure. Applications can examine individual or all ConfigDev structures with the expansion. library function 
FindConfigDevQ. 

The ConfigDev structure is defined in <libraries/configvars.h> and <./>: 



struct ConfigDev { 










struct Node 


cd Node ; 








UBYTE 


cd Flags; 


/* 


(read/write) 


*/ 


UBYTE 


cd Pad; 


/* 


reserved */ 





struct 


ExpansionRom 


cd Rom; 


/ 


APTR 






cd BoardAddr; 


/ 


ULONG 






cd BoardSize; 


/ 


UWORD 






cd_SlotAddr; 


/ 


UWORD 






cd_SlotSize; 


/ 


APTR 






cd Driver; 


/ 


struct 


Conf 


igDev 


*cd_NextCD; 


/ 


ULONG 






cd_Unused [4] ; 


/ 



}; 



copy of board's expansion ROM */ 
memory where board was placed */ 
size of board in bytes */ 
which slot number (PRIVATE) */ 
number of slots (PRIVATE) */ 
pointer to node of driver */ 
linked list of drivers to config 
for whatever the driver wants */ 



/* cd_Flags */ 

#define CDB_SHUTUP 

#define CDB CONFIGME 1 



/* this board has been shut up */ 

/* this board needs a driver to claim it */ 



#define CDF_SHUTUP 0x01 
#define CDF_CONFIGME 0x02 

The ExpansionRom structure within ConfigDev contains the board identification information that is read from the 
board's PAL or ROM at expansion time. The actual onboard identification information of a Zorro II board appears 
in the high nibbles of the first $40 words at the start of the board. Except for the first nibble pair ($00/$02) which 
when combined form er_Type, the information is stored in inverted ("ones-complement") format where binary 1's 
are represented as 0's and 0's are represented as 1's. The expansion. library reads the nibbles of expansion 
information from the board, un-inverts them (except for $00/$02 er_Type which is already un-inverted), and 
combines them to form the elements of the ExpansionRom structure. 
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The ExpansionRom structure is defined in <libraries/configregs.h> and <.£>: 



struct Expans 



ionRom { 

UBYTE er_Type; /* 

UBYTE er_Product; /* 

UBYTE er_Flags; /* 

UBYTE er_Reserved03 ; 

UWORD er_Manufacturer; /■> 

ULONG er_SerialNumber; /■> 

UWORD er_InitDiagVec; /■> 

UBYTE er_Reserved0c; 

UBYTE er_Reserved0d; 

UBYTE er_Reserved0e; 

UBYTE er ReservedOf; 



/* First 16 bytes of the expansion ROM */ 
Board type, size and flags */ 
Product number, assigned by manufacturer */ 
Flags */ 
/* Must be zero ($ff inverted) */ 

Unique ID, ASSIGNED BY COMMODORE -AMIGA! */ 
Available for use by manufacturer */ 
Offset to optional "DiagArea" structure */ 



}; 



Simple Expansion Library Example 

The following example uses FindConfigDevQ to print out information about all of the configured expansion 
peripherals in the system. FindConfigDevQ searches the system's list of ConfigDev structures and returns a 
pointer to the ConfigDev structure matching a specified board: 



newconfigdev = struct ConfigDev 



FindConf igDev ( struct ConfigDev *oldconf igdev, 
LONG manufacturer, LONG product ) 



The oldconfigdev argument may be set to NULL to begin searching at the top of the system list or, if it points to a 
valid ConfigDev, searching will begin after that entry in the system list. The manufacturer and product 
arguments can be set to search for a specific manufacturer and product by number, or, if these are set to -1 , the 
function will match any board. 



;/* findboards.c - Execute me to compile me with SAS C 5.10 

LC -bl -cfistq -v -y - j 73 findboards.c 

Blink FROM LIB : c . o, f indboards . o TO findboards LIBRARY LIB : LC . lib, LIB : Amiga . lib 

quit 

*/ 

#include <exec/types . h> 
#include <exec/memory . h> 
#include <libraries/dos . h> 



#include <libraries/conf igvars . h> 

#include <clib/exec_protos . h> 
#include <clib/expansion_protos . h> 
#include <stdlib.h> 
#include <stdio.h> 
#include <string.h> 

#ifdef LATTICE 

int CXBRK(void) { return(O); } /* Disable Lattice CTRL/C handling */ 

int chkabort (void) { return(O); } /* really */ 

#endif 

struct Library *ExpansionBase = NULL; 

void main (int argc, char **argv) 

{ 

struct ConfigDev *myCD; 
UWORD m, i ; 
UBYTE p , f , t ; 

if ( (ExpansionBase=OpenLibrary ( "expansion, library" , OL) ) —NULL) 
exit (RETURN_FAIL) ; 

/* * / 

/* FindConf igDev (oldConf igDev, manufacturer, product) */ 
/* oldConfigDev = NULL for the top of the list */ 
/* manufacturer = -1 for any manufacturer */ 

/* product = -1 for any product */ 

/* */ 

myCD = NULL; 

while (myCD=FindConf igDev(myCD, -1L, -1L) ) /* search for all ConfigDevs */ 

{ 

printf("\n ConfigDev structure found at location $%lx \n",myCD); 

/* These values were read directly from the board at expansion time */ 
printf ( "Board ID (ExpansionRom) inf ormation: \n" ) ; 

t = myCD->cd_Rom.er_Type; 

m = myCD->cd_Rom.er_Manuf acturer ; 

p = myCD->cd_Rom.er_Product ; 

f = myCD->cd_Rom.er_Flags ; 

i = myCD->cd_Rom.er_InitDiagVec; 

printf ( "er_Manuf acturer =%d=$%04x= (~$%4x) \n" , m,m, (UWORD) ~m) ; 
printf ("er_Product =%d=$%02x= (~$%2x) \n" ,p,p, (UBYTE) ~p) ; 

printf ( "er_Type =$%02x" ,myCD->cd_Rom.er_Type) ; 

if (myCD->cd_Rom.er_Type & ERTF_MEMLIST) 

printf (" (Adds memory to free list)\n"); 
else printf ( "\n" ) ; 

printf ("er_Flags =$%02x= (~$%2x) \n" , f , (UBYTE) ~f ) ; 

printf ("er_InitDiagVec =$%04x= (~$%4x) \n" , i , (UWORD)-i); 

/* These values are generated when the AUTOCONFIG (tm) software 
* relocates the board 

*/ 

printf ( "Configuration (ConfigDev) information: \n" ) ; 

printf ( "cd_BoardAddr =$%lx\n" ,myCD->cd_BoardAddr) ; 

printf ( "cd_BoardSize =$%lx (%ldK)\n", 

myCD->cd_BoardSize, ( (ULONG) myCD->cd_BoardSize) /1024) ; 

printf ( "cd_Flags =$%x" ,myCD->cd_Flags) ; 

if (myCD->cd_Flags & CDF_CONFIGME) 

printf ( "\n" ) ; 
else printf (" (driver clears CONFIGME bit)\n"); 

} 
CloseLibrary (ExpansionBase) ; 



Expansion Board Drivers 



The Amiga operating system contains support for matching up disk-based drivers with AUTOCONFIG boards. 
Though such drivers are commonly Exec devices, this is not required. The driver may, for instance, be an Exec 
library or task. Since 1 .3, the system software also supports the initialization of onboard ROM driver software. 

Disk Based Drivers 

Disk-based expansion board drivers and their icons are generally placed in the SYS:Expansion drawer of the 
user's SYS: disk or partition. The icon Tool Type field must contain the unique Hardware Manufacturer number, 
and the Product number of the expansion board(s) the driver is written for. (For more about icon Tool Type fields 
refer to the chapter on "Workbench and Icon Library".) 

The BindDrivers command issued during the disk startup-sequence attempts to match disk-based drivers with 
their expansion boards. To do this, BindDrivers looks in the Tool Types field of all icon files in SYS:Expansion. If 
the Tool Type "PRODUCT" is found in the icon, then this is an icon file for a driver. Binddrivers will then attempt 
to match the manufacturer and product number in this PRODUCT Tool Type with those of a board that was 
configured at expansion time. 
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For example, suppose you are manufacturer #1019. You have two products, #1 and #2 which both use the same 
driver. The icon for your driver for these two products would have a Tool Type set to 
"PRODUCT=1019/1 11019/2". This means: I am an icon for a driver that works with product number 1 or 2 from 
manufacturer 1019, now bind me. Spaces are not legal. Here are two other examples: 

PRODUCT=12 8/11 is the Tool Type for a driver for product 

11 from manufacturer number 1208. 
PRODUCT=1017 is the Tool Type for a driver for any 

product from manufacturer number 1017. 

If a matching board is found for the disk-based driver, the driver code is loaded and then initialized with the Exec 
InitResidentQ function. From within its initialization code, the driver can get information about the board it is 
bound to by calling the expansion. library function GetCurrentBinding(). This function will provide the driver with 
a copy of a CurrentBinding structure, including a pointer to a ConfigDev structure (possibly linked to additional 
ConfigDevs via the cd_NextCD field) of the expansion board(s) that matched the manufacturer and product IDs. 

/* this structure is used by GetCurrentBinding ( ) */ 

/* and SetCurrentBinding ( ) */ 

struct CurrentBinding { 

struct ConfigDev *cb_Conf igDev; /* first configdev in chain */ 

UBYTE * cb_FileName; /* file name of driver */ 

UBYTE * cb_ProductString; /* product # string */ 

UBYTE ** cb_ToolTypes; /* tooltypes from disk object */ 

}; 

GetCurrentBinding() allows the driver to find out the base address and other information about its board(s). The 
driver must unset the CONFIGME bit in the cd_Flags field of the ConfigDev structure for each board it intends to 
drive, and record the driver's Exec node pointer in the cd_Driver structure. This node should contain the 
LN_NAME and LN_TYPE (i.e., NT_DEVICE, NT_TASK, etc.) of the driver. 

Important Note: The GetCurrentBindingO function, and driver binding in general, must be 
bracketed by an ObtainConfigBinding() and ReleaseConfigBindingQ semaphore. The 
BindDrivers command obtains this semaphore and performs a SetCurrentBinding() before 
calling InitResidentQ, allowing the driver to simply do a GetCurrentBindingO. 

Full source code for a disk-based Expansion or DEVS: sample device driver may be found in the Addison-Wesley 
Amiga ROM Kernel Reference Manual: Devices. Autodocs for expansion. library functions may be found in the 
Addison-Wesley Amiga ROM Kernel Reference Manual: Includes and Autodocs. 



Expansion Drivers and DOS 



Two other expansion. library functions commonly used by expansion board drivers are MakeDosNodeQ and 
AddDosNode(). These functions allow a driver to create and add a DOS device node (for example DHO:) to the 
system. A new function, AddBootNodeQ, is also available in Release 2 (V36 and later versions of the OS) that 
can be used to add an autobooting DOS device node. 

MakeDosNode() requires an initialized structure of environment information for creating a DOS device node. The 
format of the function is: 

struct DeviceNode *deviceNode = MakeDosNode (parameterPkt) ; 

The parameterPkt argument is a pointer (passed in AO from assembler) to an initialized packet of environment 
parameters. 
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The parameter packet for MakeDosNodeQ consists of four longwords followed by a DosEnvec structure: 



Layout of parameter packet for MakeDosNode 



The packet for MakeDosNode starts with the following four 
longwords, directly followed by a DosEnvec structure. 



APTR dosName 
APTR execName 
ULONG unit 
ULONG flags 



Points to a DOS device name (ex. 'RAM1',0) 
Points to device driver name (ex. ' ram. device' , 0) 
Unit number 
OpenDevice flags 



The DosEnvec disk "environment" is a longword array that describes the 
disk geometry. It is variable sized, with the length at the beginning. 
Here are the constants for a standard geometry. 
See libraries/f ilehandler . i for additional notes. 
STRUCTURE DosEnvec, 



ULONG de_TableSize 
ULONG de_SizeBlock 
ULONG de_SecOrg 
ULONG de_Surfaces 
ULONG de_SectorPerBlock 
ULONG de_BlocksPerTrack 
ULONG de_Reserved 
ULONG de_PreAlloc 
ULONG de_Interleave 
ULONG de_LowCyl 
ULONG de_HighCyl 
ULONG de_NumBuffers 
ULONG de_BufMemType 
ULONG de_MaxTransfer 
ULONG de_Mask 
LONG de_BootPri 
ULONG deJDosType 



ULONG de_Baud 
ULONG de Control 



ULONG de BootBlocks 



LABEL DosEnvec SIZEOF 



Size of Environment vector 
in longwords: standard value is 128 
not used; must be 

# of heads (surfaces) . drive specific 
not used; must be 1 
blocks per track, drive specific 
DOS reserved blocks at start of partition. 
DOS reserved blocks at end of partition 
usually 

starting cylinder, typically 
max cylinder, drive specific 
Initial # DOS of buffers, 
type of mem to allocate for buffers 
Max number of bytes to transfer at a time 
Address Mask to block out certain memory 
Boot priority for autoboot 

ASCII (HEX) string showing filesystem type; 
0X444F5300 is old filesystem, 
0X444F5301 is fast file system 
Baud rate for serial handler 
Control word for handler/f ilesystem 
(used as f ilesystem/handler desires) 
Number of blocks containing boot code 
(for non-AmigaDOS filesystems) 



After making a DOS device node, drivers (except for autoboot drivers) use AddDosNode(deviceNode) to add 
their node to the system. Autoboot drivers will instead use the new Release 2 expansion. library AddBootNode() 
function (if running under V36 or higher) or the Exec Enqueue() function (if running under pre-V36) to add a 
BootNode to the ExpansionBase.eb MountList. 



ROM Based and Autoboot Drivers 

Since 1.3, the system software supports the initialization of ROM drivers residing on expansion peripherals, 
including the ability for drivers to provide a DOS node which the system can boot from. This feature is known as 
Autoboot. 

Automatic boot from a ROM-equipped expansion board is accomplished before DOS is initialized. This facility 
makes it possible to automatically boot from a hard disk without any floppy disks inserted. Likewise, it is possible 
to automatically boot from any device which supports the ROM protocol, even allowing the initialization of a disk 
operating system other than the Amiga's dos. library. ROM-based drivers contain several special entry points that 
are called at different stages of system initialization. These three stages are known as DIAG, ROMTAG INIT and 
BOOT. 
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Events At DIAG Time 



When your AUTOCONFIG hardware board is configured by the expansion initialization routine, its 
ExpansionRom structure is copied into the ExpansionRom subfield of a ConfigDev structure. This ConfigDev 
structure will be linked to the expansion. library's private list of configured boards. 

After the board is configured, the er_Type field of its ExpansionRom structure is checked. The DIAGVALID bit 
set declares that there is a valid DiagArea (a ROM/diagnostic area) on this board. If there is a valid DiagArea, 
expansion next tests the erJnitDiagVec vector in its copy of the ExpansionRom structure. This offset is added 
to the base address of the configured board; the resulting address points to the start of this board's DiagArea. 

struct ExpansionRom 

{ 

- if ERTB_DIAGVALID set */ 



UBYTE 


er 


Type ; 




/* 


UBYTE 


er 


Product ; 




UBYTE 


er 


Flags; 




UBYTE 


er 


Reserved03 ; 




UWORD 


er 


Manufacturer ; 




ULONG 


er 


SerialNumber ; 




UWORD 


er 


InitDiagVec; 


/* 


UBYTE 


er 


ReservedOc 




/* 


UBYTE 


er 


ReservedOd 




/* 


UBYTE 


er 


ReservedOe 






UBYTE 


er 


ReservedOf 







then er_InitDiagVec 

is added to cd_BoardAddr 

and points to DiagArea 



}; 
Now expansion knows that there is a DiagArea, and knows where it is. 



struct DiagArea 



UBYTE 


da_ 


Conf ig; 


UBYTE 


da] 


Flags ; 


UWORD 


da" 


Size; 


UWORD 


da] 


DiagPoint ; 


UWORD 


da] 


BootPoint; 


UWORD 


da] 


Name ; 


UWORD 


da] 


ReservedOl ; 


UWORD 


da_ 


_Reserved02 ; 



/" 



if DAC CONFIGTIME is set */ 



/* <-- then da_Size bytes will */ 
/* be copied into RAM */ 



}; 



/* da_Config definitions */ 
#define DAC_BUSWIDTH OxCO 
#define DAC_NIBBLEWIDE 0x00 
#define DAC_BYTEWIDE 0x40 
#define DAC WORDWIDE 0x80 



/* two bits for bus width */ 

/* invalid for 1.3 - see note below */ 



#define DAC_BOOTTIME 0x30 
#define DAC_NEVER 0x0 
#define DAC CONFIGTIME 0x10 



/* two bits for when to boot */ 

/* obvious */ 

/* call da BootPoint when first 



#define DAC BINDTIME 



configging the device */ 
0x2 /* run when binding drivers to boards */ 



Next, expansion tests the first byte of the DiagArea structure to determine if the CONFIGTIME bit is set. If this bit 
is set, it checks the da_BootPoint offset vector to make sure that a valid bootstrap routine exists. If so, 
expansion copies da_Size bytes into RAM memory, starting at beginning of the DiagArea structure. 

The copy will include the DiagArea structure itself, and typically will also include the da_DiagPoint 
ROM/diagnostic routine, a Resident structure (romtag), a device driver (or at least the device initialization tables 
or structures which need patching), and the da_BootPoint routine. In addition, the BootNode and parameter 
packet for MakeDosNode() may be included in the copy area for Diag-time patching. Strings such as DOS and 
Exec device names, library names, and the romtag ID string may also be included in the copy area so that both 
position-independent ROM code and position-independent routines in the copy area may reference them PC 
relative. 
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The copy will be made either nibblewise, or wordwise, according to the BUSWIDTH subfield of da_Config. Note 
that the da_BootPoint offset must be non-NULL, or else no copy will occur. (Note - under 1 .3, DAC_BYTEWIDE 
is not supported. Byte wide ROMs must use DAC_NIBBLEWIDE and drivers must supply additional code to 
re-copy their DiagArea) 

The following illustrates an example Diag copy area, and specifies the various fields which should be coded as 
relative offsets for later patching by your DiagPoint routine. 

Example DiagArea Copy in RAM 



DiagStart : 



CCFF 
SIZE 
DIAG 
BOOT 

NAME 
0000 
0000 



a struct DiagArea 
da_Config, da_Flags 
da_Size 
da_DiagPoint 
da_Boot Point 
da_Name 
da_Reserved01 
da Reserved02 



coded as EndCopy-DiagStart 
coded as DiagEntry-DiagStart 
coded as BootEntry-DiagStart 
coded as DevName -DiagStart 
Above fields above are supposed 
to be relative. No patching needed 



Romtag : 



a struct Resident ("Romtag") 

RT_MATCHTAG, RT_ENDSKIP, RT_NAME and RT_IDSTRING 
addresses are coded relatively as label-DiagStart . 
The RT_INIT vector is coded as a relative offset 
from the start of the ROM. DiagEntry patches these. 



DevName : 



ssss..O ; The name string for the exec device IdString: 
iiii..O ; The ID string for the Romtag 



BootEntry: BBBB 
DiagEntry: DDDD 



Boot -time code 

Diag-time code (position independent) 
When called, performs patching of the relative- 
coded addresses which need to be absolute. 



OtherData: 



dddd 
bbbb 
PPPP 



Device node or structs/tables (patch names, vectors) 
BootNode (patch ln_Name and bn_DeviceNode) 
MakeDosNode packet (patch dos and exec names) 



ssss 



other name, ID, and library name strings 



EndCopy : 

Now the ROM "image" exists in RAM memory. Expansion stores the ULONG address of that "image" in the 
UBYTES er_Reserved0c, Od, Oe and Of. The address is stored with the most significant byte in er_Reserved0c, 
the next to most significant byte in er_Reserved0d, the next to least significant byte in er_Reserved0e, and the 



least significant byte in er_ReservedOf - i.e., it is stored as a longword at the address er_ReservedOc. 

Expansion finally checks the da_DiagPoint offset vector, and if valid executes the ROM/diagnostic routine 
contained as part of the ROM "image". This diagnostic routine is responsible for patching the ROM image so that 
required absolute addresses are relocated to reflect the actual location of code and strings, as well as performing 
any diagnostic functions essential to the operation of its associated AUTOCONFIG board. The structures which 
require patching are located within the copy area so that they can be patched at this time. Patching is required 
because many of the structures involved require absolute pointers to such things as name strings and code, but 
the absolute locations of the board and the RAM copy area are not known when code the structures. 
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The patching may be accomplished by coding pointers which require absolute addresses instead as relative 
offsets from either the start of the DiagArea structure, or the start of the board's ROM (depending on whether the 
final absolute pointer will point to a RAM or ROM location). The Diag routine is passed both the actual base 
address of the board, and the address of the Diag copy area in RAM. The routine can then patch the structures in 
the Diag copy area by adding the appropriate address to resolve each pointer. 

Example DiagArea and Diag patching routine: 

** Sample autoboot code fragment 

** These are the calling conventions for the Diag routine 






A7 -- points to at least 2K of stack 

A6 -- ExecBase 

A5 -- ExpansionBase 

A3 -- your board's ConfigDev structure 

A2 -- Base of diag/init area that was copied 

AO -- Base of your board 



* * 

* * 



Your Diag routine should return a non-zero value in DO for success. 
If this value is NULL, then the diag/init area that was copied 
** will be returned to the free memory pool. 



INCLUDE "exec/types . i" 

INCLUDE "exec/nodes . i" 

INCLUDE "exec/resident . i" 

INCLUDE "libraries/conf igvars . i" 

; LVO's resolved by linking with library amiga.lib 
XREF _LVOFindResident 

ROMINFO EQU 1 
ROMOFFS EQU $0 

* ROMINFO defines whether you want the AUTOCONFIG information in 

* the beginning of your ROM (set to if you instead have PALS 

* providing the AUTOCONFIG information instead) 

* ROMOFFS is the offset from your board base where your ROMs appear. 

* Your ROMs might appear at offset and contain your AUTOCONFIG 

* information in the high nibbles of the first $40 words ($80 bytes) . 

* Or, your autoconfig ID information may be in a PAL, with your 

* ROMs possibly being addressed at some offset (for example $2000) 

* from your board base. This ROMOFFS constant will be used as an 

* additional offset from your configured board address when patching 

* structures which require absolute pointers to ROM code or data. 

* We'll store Version and Revision in serial number 

VERSION EQU 3 7 ; also the high word of serial number 

REVISION EQU 1 ; also the low word of serial number 

* See the Addison-Wesley Amiga Hardware Manual for more info. 

MANUF_ID EQU 2011 ; CBM assigned (2011 for hackers only) 

PRODUCT_ID EQU 1 ; Manufacturer picks product ID 



BOARDS I ZE 
SIZE FLAG 



EQU 
EQU 



$40000 
3 



; How much address space board decodes 
Autoconfig 3 -bit flag for BOARDSIZE 
0=$800000 (8meg) 4=$80000 (512K) 
1=$10000 (64K) 5=$100000 (lmeg) 
2=$20000 (128K) 6=$2 00000 ( 2meg) 
3=$40000 (256K) 7=$400000 (4meg) 



******* RomStart *************************************************** 
********************************************************************** 



RomStart : 

IFGT ROMINFO 

ExpansionRom structure 

Note - If you implement your ExpansionRom and ExpansionControl 
with PALS, then you can comment out everything until DiagStart : 
(ie. Make ROMID EQU 0) 

; High nibbles of first two words ($00, $02) are er_Type (not inverted) 

er_Type 
dew $D000 ; llxx normal board type 

xxOx not in memory free list 
xxxl Diag valid (has driver) 
Oxxx not chained 
xnnn flags board size 



dew (SIZE_FLAG<<12) &$7000 



; High nibbles of next two words are er_Product 

; These are inverted (~) , as are all other words except $4 and $42 



dc .w 

dc .w 
dc .w 
dc .w 



dc .w 
dc .w 



dc .w 
dc .w 
dc .w 
dc .w 





dc 


w 




dc 


w 




dc 


w 




dc 


w 




dc 


w 




dc 


w 




dc 


w 




dc 


w 


IFNE 


*-I 


to 


FAIL 


"E: 


<P 


ENDC 







. er_Product 
■ (PRODUCT_ID<<8) ) &$f 000, (~ ( PRODUCT_ID<<12 ) ) &$f 000 



-$C000) &$f 000 

-0) &$f 000 

-0) &$f 000, (~0) &$f 000 



er_Flags 

-lxxx board is moveable 
-xlxx board can't be shut up 



er Reserved03 



; er_Manuf acturer 
~ (MANUF_ID) ) &$f 000, (~ (MANUF_ID<<4 ) ) &$f 000 
~ (MANUF_ID<<8) ) &$f 000, (~ (MANUF_ID<<12 ) ) &$f000 

; er_SerialNumber 
- (VERSION) ) &$f 000, (~ (VERSION<<4) ) &$f000 
- (VERSION<<8) ) &$f 000, (~ ( VERSION<<12 ) ) &$f 000 
- (REVISION) ) &$f 000, (~ (REVISION<<4) ) &$f000 
- (REVISION<<8) ) &$f 000, (~ (REVISION<<12 ) ) &$f000 

; er_InitDiagVec 
- ( (DiagStart-RomStart) ) ) &$f 000 
- ( (DiagStart-RomStart) <<4) ) &$f 000 
- ( (DiagStart-RomStart) <<8) ) &$f 000 
- ( (DiagStart-RomStart) <<12) ) &$f 000 



-0) &$f 000, (~0) &$f 000 
-0) &$f 000, (~0) &$f 000 
-0) &$f 000, (~0) &$f 000 
-0) &$f 000, (~0) &$f 000 



er_Reserved0c 
er_Reserved0d 
er_Reserved0e 
er ReservedOf 



RomStart -$4 
ExpansionRom structure not the right size" 



nibbles $40 and $42 are not to be inverted 

ec_Interrupt (no interrupts) 
ec_Reservedll 

ec_BaseAddress (write only) 
ec_Shutup (write only) 



;Note 

dew (0) &$f 000, (0) &$f000 

dew (~0) &$f 000, (~0) &$f000 

dew (~0) &$f 000, (~0) &$f000 

dew (~0) &$f 000, (-0) &$f 000 



dc . w 

dc .w 
dc .w 
dc .w 
dc .w 
dc .w 
dc .w 
dc .w 
dc .w 
dc .w 
dc .w 
dc . w 



-0) &$f 000, 
-0) &$f000, 
-0) &$f000, 
-0) &$f 000, 
-0) &$f000, 
-0) &$f000, 
-0) &$f000, 
-0) &$f 000, 
-0) &$f000, 
-0) &$f 000, 
-0) &$f000, 
-0) &$f000, 



-0) &$f 000 
-0) &$f000 
-0) &$f000 
-0) &$f000 
-0) &$f000 
-0) &$f000 
-0) &$f000 
-0) &$f000 
-0) &$f000 
-0) &$f000 
-0) &$f000 
-0) &$f000 



ec_Reservedl4 
ec_Reservedl5 
ec_Reservedl6 
ec_Reservedl7 
ec_Reservedl8 
ec_Reservedl9 
ec_Reservedla 
ec_Reservedlb 
ec_Reservedlc 
ec_Reservedld 
ec_Reservedle 
ec Reservedlf 



IFNE 
FAIL 
ENDC 



*-RomStart-$80 

"Expansion Control structure not the right size" 



; ROMINFO 



* * * * * ■* * 



DiagStart 



************************************************** 



DiagStart ; 



This is the DiagArea structure whose relative offset from 
your board base appears as the Init Diag vector in your 
autoconfig ID information. This structure is designed 
to use all relative pointers (no patching needed) . 



dc . b DAC_WORDWIDE+DAC_CONFIGTIME 

dc.b 

dew EndCopy-DiagStart 

dew DiagEntry-DiagStart 

dew BootEntry-DiagStart 

dew DevName -DiagStart 

dew 

dew 



da_Conf ig 
da_Flags 
da_Size 
da_DiagPoint 
da_Boot Point 
da_Name 
da_Re servedOl 
da Reserved02 



******* 


Reside 


;nt 


St ructur6 ************************■*■■*'■*'■*'■*'■*' 


Romtag: 
















dc 


w 


RTC_MATCHWORD 


UWORD 


RT 


MATCHWORD 


rt Match 


dc 


1 


Romtag -DiagStart 


APTR 


RT 


MATCHTAG 


rt End: 


dc 


1 


EndCopy-DiagStart 


APTR 


RT 


ENDSKIP 




dc 


b 


RTW_COLDSTART 


UBYTE 


RT 


FLAGS 




dc 


b 


VERSION 


UBYTE 


RT 


VERSION 




dc 


b 


NT_DEVICE 


UBYTE 


RT 


_TYPE 




dc 


b 


20 


BYTE 


RT 


_PRI 


rt Name : 


dc 


1 


DevName -DiagStart 


APTR 


RT 


NAME 


rt_Id: 


dc 


1 


IdSt ring -DiagStart 


APTR 


RT 


_IDSTRING 


rt Init: 


dc 


1 


Init-RomStart 


APTR 


RT 


INIT 



************************ 



******* strings referenced in Diag Copy area 

DevName: dc.b ' abc .device' , ; Name string 

IdString dc.b 'abc ' , 4 8+VERSION, ' . ' , 4 8+REVISION ; Id string 



DosName : dc.b 
DosDevName : dc . b 



' dos . library' , ; DOS library name 

'ABC',0 ; dos device name for MakeDosNode ( ) 
; (dos device will be ABC:) 



ds . w 







; word align 



******* 



DiagEntry ************************************************** 
********************************************************************** 



* success = DiagEntry (BoardBase,DiagCopy, configDev) 

* dO aO a2 a3 
* 

* Called by expansion architecture to relocate any pointers 

* in the copied diagnostic area. We will patch the romtag. 

* If you have pre-coded your MakeDosNode packet, BootNode, 

* or device initialization structures, they would also need 

* to be within this copy area, and patched by this routine. 
* 
********************************************************************** 



DiagEntry: 



lea patchTable-RomStart (aO) , al ; find patch table 
adda.l #ROMOFFS,al ; adjusting for ROMOFFS 

* Patch relative pointers to labels within DiagCopy area 

* by adding Diag RAM copy address. These pointers were coded as 

* long relative offsets from base of the DiagArea structure. 



dpatches : 
dloop: 



move .1 a2 , dl 



move . w 
bmi . s 
add.l 
bra. s 



(al) +,d0 
bpatches 
dl, (a2,d0.w) 
dloop 



;dl=base of ram Diag copy 

dO=word offs. into Diag needing patch 
-1 is end of word patch offset table 
add DiagCopy addr to coded rel . offset 



* Patches relative pointers to labels within the ROM by adding 

* the board base address + ROMOFFS. These pointers were coded as 

* long relative offsets from RomStart . 



bpatches : 



rloop: 



move .1 aO , dl 
add.l #ROMOFFS,dl 

move . w (al) + , do 

bmi . s endpatches 

add.l dl, (a2,d0.w) 

bra.s rloop 



;dl = board base address 

;add offset to where your ROMs are 

dO=word offs. into Diag needing patch 

-1 is end of patch offset table 

add ROM address to coded relative offset 



endpatches : 



moveq.l #l,dO 
rts 



; indicate "success" 



-k -k -k -k -k -k -k 



BootEntry ************************************************** 
********************************************************************** 



BootEntry: lea 
jsr 



DosName (PC) , al 
_LVOFindResident (a6) 

move . 1 dO,aO 

move.l RT_INIT(A0) ,a0 

jsr (aO) 

rts 



' dos . library' , 
find the DOS resident tag 
in order to bootstrap 
set vector to DOS INIT 
and initialize DOS 



* End of the Diag copy area which is copied to RAM 
* 

EndCopy : 
************************************************************************* 

************************************************************************* 
* 

* Beginning of ROM driver code and data that is accessed only in 

* the ROM space. This must all be position-independent. 



patchTable: 

* Word offsets into Diag area where pointers need Diag copy address added 

dew rt_Match-DiagStart 

dew rt_End-DiagStart 

dew rt_Name-DiagStart 

dew rt_Id-DiagStart 

dew -1 

* Word offsets into Diag area where pointers need boardbase+ROMOFFS added 

dew rt_Init-DiagStart 
dew -1 

******* Romt act Ini t Ent rv ********************************************** 
************************************************************************* 



Init : 



After Diag patching, our romtag will point to this 
routine in ROM so that it can be called at Resident 
initialization time. 
This routine will be similar to a normal expansion device 



initialization routine, but will MakeDosNode then set up a 
BootNode, and Enqueue!) on eb_MountList . 



Rest of your position- independent device code goes here. 



Your da DiagPoint ROM/diagnostic routine should return a non-zero value to indicate success; otherwise the 
ROM "image" will be unloaded from memory, and its address will be replaced with NULL bytes in locations 
er_ReservedOc, Od, Oe and Of. 

Now that the ROM "image" has been copied into RAM, validated, and linked to board's ConfigDev structure, the 
expansion module is free to configure all other boards on the utility.library's private list of boards. 

766 Amiga ROM Kernel Reference Manual: Libraries 

It may help to see just how a card's ROM AUTOCONFIG information corresponds to the ExpansionRom 
structure. This chart shows the contents of on-card memory for a fictional expansion card. Note that the 
ExpansionRom. Flags field ($3F in addresses $08/$0A below) is shown interpreted in its inverted form of $3F. 
Once the value is uninverted to become $C0, you should use the #defines in <\ibraries/configregs.h> to interpret 
it. 

Table 32-1 : Sample Zorro II AUTOCONFIG ROM Information Viewed as a Hex Dump 

FLAG AND FIELD DEFINITIONS THIS BOARD 



lxxx chained 

xlll size 

0=8meg, 01=64K, 01 0=12 8K, etc. 



llxx type / 
xxlx addmem / 
xxx 1 ROM / 

\ / ~Prod# 
\ / / \ 



lxxx nopref 
xlxx canshut 
xxll reserved 
/ 
/ res . reserved 



0000: D0003000 F000E000 3000F000 F000F000 



11 = Normal type 
Don' t addmem 
ROM Vector Valid 
Not chained 
Size 256K 
Product#=~$FE=l 
Flags=~$3F=$C0 
Prefer exp space 
Can't be shut up 



-Manufacturers -HiWord Serial# 
/ / \ \ / / \ \ 
0010: F0008000 20004000 F000F000 D000A000 



Manu#=~$F824=$7DB=2 011 
HiSer=~$FFDA=$0 02 5=3 7 



-LoWord Serialtt -Rom Vector LoSer=~$FFFE=$0001=l 
/ / \ \ / / \ \ Rom Vector=~$FF7F=$80 
0020: F000F000 F000E000 F000F000 7000F000 from board base 



The AUTOCONFIG information from the above card would appear as follows in an ExpansionRom structure: 



Nibble Pairs 

00/02 

04/06 

08/OA 

10/12 and 14/16 

18/1A thru 24/26 

28/2A and 2C/2E 



ExpansionRom Field 

er_Type 

er_Product 

er_Flags 

er_Manuf acturer 

er_SerialNumber 

er_InitDiagVec 



Value 

$D3 

$01 = 

$C0 

$0 7DB 

$00250001 

$0080 



2011 



If a card contains a ROM driver (Rom Vector valid), and the vector is at offset $80 (as in this example) the 
DiagArea structure will appear at offset $0080 from the base address of the board. This example card's 
Resident structure (romtag) directly follows its DiagArea structure. 



WORDWIDE + CONFIGTIME ROMTAG 

\ flags DiagPt Devname starts 
\ \ DAsize / BootPt / here DiagPt, BootPt, 

\ \ /\ /\ /\ /\ res. res. /\ DevName relative 
0080: 90000088 004A0076 00280000 00004AFC to Diag struct 

COLDSTART NT_DEVICE backptr , endskip, 

\ ver /priority and DevName coded 

backptr endskip \ \ / / DevName relative, patched 

0090: 0000000E 00000088 01250314 00000028 at Diag time 

ID and InitEntry 
IDstring InitEntry coded relative, 

00A0: 00000033 00000116 patched at Diag 
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Events At ROMTAG INIT Time 

Next, most resident system modules (for example graphics) are initialized. As part of the system initialization 
procedure a search is made of the expansion. library's private list of boards (which contains a ConfigDev structure 
for each of the AUTOCONFIG hardware boards). If the cd_Flags specify CONFIGME and the er_Type specifies 
DIAGVALID, the system initialization will do three things: 

First, it will set the current ConfigDev as the current binding (see the expansion. library SetCurrentBindingO 
function). Second, it will check the DiagArea's da_Config flag to make sure that the CONFIGTIME bit is set. 
Third, it will search the ROM "image" associated with this hardware board for a valid Resident structure 
(<exec/resident.h>); and, if one is located, will call InitResidentQ on it, passing a NULL segment list pointer as 
part of the call. 

Next, the board's device driver is initialized. The Resident structure associated with this board's device driver 
(which has now been patched by the ROM/diagnostic routine) should follow standard system conventions in 
initializing the device driver provided in the boot ROMs. This driver should obtain the address of its associated 
ConfigDev structure via GetCurrentBinding(). 

Once the driver is initialized, it is responsible for some further steps. It must clear the CONFIGME bit in the 
cd_Flags of its ConfigDev structure, so that the system knows not to configure this device again if binddrivers is 
run after bootstrap. Also, though it is not currently mandatory, the driver should place a pointer to its Exec node in 
the cd_Driver field of the ConfigDev structure. This will generally be a device (NT_DEVICE) node. And for this 
device to be bootable, the driver must create a BootNode structure, and link this BootNode onto the 
expansion. library's eb_MountList. 

The BootNode structure (see <libraries/expansionbase.h>) contains a Node of the new type NTBOOTNODE 
(see <exec/nodes.h>). The driver must initialize the ln_Name field to point to the ConfigDev structure which it 
has obtained via the GetCurrentBindingQ call. The bn_Flags subfield is currently unused and should be 
initialized to NULL. The bn_DeviceNode must be initialized to point to the DosNode for the device. 

When the DOS is initialized later, it will attempt to boot from the first BootNode on the eb_MountList. The 
eb MountList is a priority sorted List, with nodes of the highest priority at the head of the List. For this reason, 
the device driver must enqueue a BootNode onto the list using the Exec library function Enqueue(). 

In the case of an autoboot of AmigaDOS, the BootNode must be linked to a DeviceNode of the AmigaDOS type 
(see <libraries/filehandler.h>), which the driver can create via the expansion library MakeDosNode() function call. 
When the DOS "wakes up", it will attempt to boot from this DeviceNode. 

Events At BOOT Time 

If there is no boot disk in the internal floppy drive, the system strap module will call a routine to perform autoboot. 
It will examine the eb_MountList; find the highest priority BootNode structure at the head of the List; validate the 
BootNode; determine which ConfigDev is associated with this BootNode; find its DiagArea; and call its 
da_BootPoint function in the ROM "image" to bootstrap the appropriate DOS. Generally, the BootPoint code of 
a ROM driver will perform the same function as the boot code installed on a floppy disk, i.e., it will FindResident() 
the dos. library, and jump to its RTJNIT vector. The da_BootPoint call, if successful, should not return. 
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If a boot disk is in the internal floppy drive, the system strap will Enqueue() a BootNode on the eb_MountList for 
DFO: at the suggested priority (see the Autodoc for the expansion. library AddDosNodeQ function). Strap will then 
open AmigaDOS, overriding the autoboot. AmigaDOS will boot from the highest priority node on the 
eb MountList which should, in this case, be DFO:. Thus, games and other bootable floppy disks will still be able 
to obtain the system for their own use. 

In the event that there is no boot disk in the internal floppy drive and there are no ROM bootable devices on the 
autoconfiguration chain, the system does the normal thing, asking the user to insert a Workbench disk, and 
waiting until its request is satisfied before proceeding. 

RigidDiskBlock and Alternate Filesystems 

Through the use of RigidDiskBlock information and the FileSys. resource, it is possible for an autoboot driver to 
have access to enough information to mount all of its device partitions and even load alternate filesystems for use 
with these partitions. 

The RigidDiskBlock specification (also known as "hardblocks") defines blocks of data that exist on a hard disk to 
describe that disk. These blocks are created or modified with an installation utility (such as the hard drive Prep 
utility for the A2090A ST506/SCSI controller card) provided by the disk controller manufacturer, and they are read 
and used by the device driver ROM (or expansion) code. They are not generally accessible to the user as they do 
not appear on any DOS device. The blocks are tagged with a unique identifier, checksummed, and linked 
together. 

The five block types currently defined are RigidDiskBlock, BadBlockBlock, PartitionBlock, 
FileSysHeaderBlock, and LoadSegBlock. 

The root of these blocks is the RigidDiskBlock. The RigidDiskBlock must exist on the disk within the first 
RDB_LOCATION_LIMIT (16) blocks. This inhibits the use of the first cylinder(s) in an AmigaDOS partition: 
although it is strictly possible to store the RigidDiskBlock data in the reserved area of a partition, this practice is 
discouraged since the reserved blocks of a partition are overwritten by Format, Install, DiskCopy, etc. The 
recommended disk layout, then, is to use the first cylinder(s) to store all the drive data specified by these blocks: 
i.e. partition descriptions, file system load images, drive bad block maps, spare blocks, etc. This allocation range 
is described in the RigidDiskBlock. 

The RigidDiskBlock contains basic information about the configuration of the drive: number and size of blocks, 
tracks, and cylinders, as well as other relevant information. The RigidDiskBlock points to bad block, partition, file 
system and drive initialization description blocks. 

The BadBlockBlock list contains a series of bad-block/good-block pairs. Each block contains as many as will fit 
in a physical sector on the drive. These mappings are to be handled by the driver on read and write requests. 

The drive initialization description blocks are LoadSegBlocks that are loaded at boot time to perform 
drive-specific initialization. They are called with both C-style parameters on the stack, and assembler parameters 
in registers as follows: 

do = Drivelnit (lun, rdb, ior) (dO/aO/al) 

where lun is the SCSI logical unit number (needed to construct SCSI commands), rdb is a pointer to a memory 
copy of the RigidDiskBlock (which should not be altered), and ior is a standard IO request block that can be 
used to access the drive with synchronous DolO() calls. 
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The result of Drivelnit() is either -1 , 0, or 1 . A -1 signifies that an error occurred and drive initialization cannot 
continue. A (zero) result reports success. In cases -1 and 0, the code is unloaded. A result of 1 reports 
success, and causes the code to be kept loaded. Furthermore, this resident code will be called whenever a reset 
is detected on the SCSI bus. 

The FileSysHeaderBlock entries contain code for alternate file handlers to be used by partitions. There are 
several strategies that can be used to determine which of them to load. The most robust would scan all drives for 
those that are both required by partitions and have the highest fhb_Version, and load those. Whatever method is 



used, the loaded file handlers are added to the Exec resource FileSystem. resource, where they are used as 
needed to mount disk partitions. 

The PartitionBlock entries contains most of the data necessary to add each partition to the system. They 
replace the Mount and DEVS:MountList mechanism for adding these partitions. The only items required by the 
expansion. library MakeDosNodeQ function which are not in this partition block are the Exec device name and 
unit, which is expected to be known by driver reading this information. The file system to be used is specified in 
the pb_Environment. If it is not the default file system (i.e., 'DOSWO' or 'DOSW1'), the node created by 
MakeDosNodeQ is modified as specified in a FileSystem. resource's FileSysEntry before adding it to the DOS 
list. 

Only 512 byte blocks were supported by the pre-V36 file system, but this proposal was forward-looking by making 
the block size explicit, and by using only the first 256 bytes for all blocks but the LoadSeg and BadBlock data. 
Under the present filesystem, this allows using drives formatted with sectors 256 bytes or larger (i.e., 256, 512, 
1 024, etc). LoadSeg and BadBlock data use whatever space is available in a sector. 

RigidDiskBlock 

This is the current specification for the RigidDiskBlock: 



rdb_ID 
rdb_SummedLongs 

rdb_ChkSum 

rdb HostID 



== 'RDSK' 
= = 64 

block checksum (longword sum to zero) 

SCSI Target ID of host 

This is the initiator ID of the creator of this 
RigidDiskBlock. It is intended that 
modification of the RigidDiskBlock, or of any 
of the blocks pointed to by it, by another 
initiator (other than the one specified here) 
be allowed only after a suitable warning. The 
user is then expected to perform an audio 
lock out ("Hey, is anyone else setting up SCSI 
stuff on this bus?") . The rdb_HostID may 
become something other than the initiator ID 
when connected to a real network: that is an 
area for future standardization. 



rdb_BlockBytes 



size of disk blocks 

Under pre-V36 filesystem, this must be 512 for 
a disk with any AmigaDOS partitions on it. 
Present filesystem supports 256, 512, 1024, etc. 



rdb_Flags 

RDBF . LAST 



longword of flags : 

no disks exist to be configured after this 
one on this controller (SCSI bus) . 



RDBF . LASTLUN 



no LUNs exist to be configured greater 
than this one at this SCSI Target ID 



RDBF. LASTTID 



no Target IDs exist to be configured 
greater than this one on this SCSI bus 
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RDBF._NORESELECT don't bother trying to perform reselection 
when talking to this drive 



RDBF. DISKID 



rdb_Disk... identification variables below 
contain valid data. 



RDBF. CTRLRID 



rdb Controller. 



identification variables 



below contain valid data. 



RDBF . SYNCH 



drive supports scsi synchronous mode 
CAN BE DANGEROUS TO USE IF IT DOESN'T! 



These fields point to other blocks on the disk which are not a part of any filesystem. All block pointers referred to 
are block numbers on the drive. 



rdb BadBlockList 



optional bad block list 

A singly linked list of blocks of type 

PartitionBlock 



rdb PartitionList 



optional first partition block 

A singly linked list of blocks of type 

PartitionBlock 



rdb_FileSysHeaderList optional file system header block 

A singly linked list of blocks of type 
FileSysHeaderBlock 



rdb Drivelnit 



optional drive-specific init code 
A singly linked list of blocks of type 
LoadSegBlock containing initialization code. 
Called as Drivelnit (lun, rdb, ior) (dO/aO/al) . 



rdb Reservedl [6] 



set to $ffffffffs 
These are reserved for future block lists. 
Since NULL for block lists is $ffffffff, these 
reserved entries must be set to $ffffffff. 



These fields describe the physical layout of the drive. 



rdb_Cylinders 
rdb_Sectors 
rdb Heads 



number of drive cylinders 
sectors per track 
number of drive heads 



rdb Interleave 



interleave 

This drive interleave is independent from, and 
unknown to, the DOS's understanding of 
interleave as set in the partition's 
environment vector. 



rdb_Park 

rdb Reserved2 [3] 



landing zone cylinder 
set to zeros 



These fields are intended for ST506 disks. They are generally unused for SCSI devices and set to zero. 



rdb_WritePreComp 
rdb_ReducedWrite 
rdb_StepRate 
rdb Reserved3 [5] 



starting cylinder: write precompensation 
starting cylinder: reduced write current 
drive step rate 
set to zeros 



These fields are used while partitions are set up to constrain the partitionable area and help describe the 
relationship between the drive's logical and physical layout. 



rdb RDBlocksLo 



low block of the range allocated for 
blocks described here . Replacement blocks 
for bad blocks may also live in this range. 

Expansion Library 771 



rdb_RDBlocksHi 
rdb_LoCyl inder 



high block of this range (inclusive) 
low cylinder of partitionable disk area 



rdb_HiCylinder 
rdb_CylBlocks 



Blocks described by this include file will 
generally be found in cylinders below this one. 

high cylinder of partitionable data area 
Usually rdb_Cylinders-l . 

number of blocks available per cylinder 
This may be rdb_Sectors*rdb_Heads, but a SCSI 
disk that, for example, reserves one block per 
cylinder for bad block mapping would use 
rdb Sectors*rdb Heads- 1. 



rdb AutoParkSeconds 



number of seconds to wait before parking 
drive heads automatically. If zero, this 
feature is not desired. 



rdb_HighRDSKBlock 



highest block used by these drive definitions 
Must be less than or equal to rdb_RDBBlocksHi . 
All replacements for bad blocks should be 
between rdb_HighRDSKBlock+l and rdb_RDBBlocksHi 
(inclusive) . 



rdb Reserved4 



set to zeros 



These fields are of the form available from a SCSI Identify command. Their purpose is to help the user identify the 
disk during setup. Entries exist for both controller and disk for non-embedded SCSI disks. 



rdb_DiskVendor 

rdb_DiskProduct 

rdb_DiskRevision 

rdb_ControllerVendor 

rdb_Cont roller Product 

rdb_ControllerRevision 

rdb_Reserved5 [10] 

BadBlockBlock 



vendor name of the disk 

product name of the disk 

revision code of the disk 

vendor name of the disk controller 

product name of the disk controller 

revision code of the disk controller 

set to zeros 



This is the current specification for the BadBlockBlock. The end of data occurs when bbb_Next is NULL 
($FFFFFFFF), and the summed data is exhausted. 



bbb ID 



' BADB ' 



bbb_SummedLongs 



size of this checksummed structure 
Note that this is not 64 like most of the other 
structures. This is the number of valid longs 
in this image, and can be from 6 to 
rdb_BlockBytes/4 . The latter is the best size 
for all blocks other than the last one. 



bbb_ChkSum 
bbb HostID 



block checksum (longword sum to zero) 

SCSI Target ID of host 

This describes the initiator ID for the creator 

of these blocks. (see rdb HostID discussion) 



bbb_Next 
bbb Reserved 



block number of the next BadBlockBlock 
set to zeros 



bbb BlockPairs [61] 



pairs of block remapping information 

The data starts here and continues as long as 

indicated by bbb_SummedLongs-6 : e.g. If 
bbb_SummedLongs is 128 (512 bytes) , 61 pairs 
are described here. 
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PartitionBlock 



This is the current specification for the PartitionBlock. Note that while reading these blocks you may encounter 
partitions that are not to be mounted because the pb_HostlD does not match, or because the pb_DriveName is 
in use and no fallback strategy exists, or because PBF._NOMOUNT is set, or because the proper filesystem 
cannot be found. Some partitions may be mounted but not be bootable because PBF._BOOTABLE is not set. 



pb_ID 

pb_SummedLongs 

pb_ChkSum 

pb_HostID 



== 'PART' 

= = 64 

block checksum (longword sum to zero) 

SCSI Target ID of host 

This describes the initiator ID for the owner 

of this partition. (see rdb_HostID discussion) 



pb_Next 
pb_Flags 

PBF . BOOTABLE 



block number of the next PartitionBlock 

see below for defines 

this partition is intended to be bootable 
(e.g. expected directories and files exist) 



PBF . NOMOUNT 



pb_Reservedl [2] 



this partition description is to reserve 
space on the disk without mounting it. 
It may be manually mounted later. 
set to zeros 



pb_DevFlags 
pb_DriveName 



preferred flags for OpenDevice 

preferred DOS device name : BSTR form 

This name is not to be used if it is already 

in use . 



Note that pb_Reserved2 will always be at least 4 longwords so that the RAM image of this record may be 
converted to the parameter packet to the expansion. library function MakeDosNode(). 



pb_Reserved2 [15] 



filler to make 32 longwords so far 



The specification of the location of the partition is one of the components of the environment, below. If possible, 
describe the partition in a manner that tells the DOS about the physical layout of the partition: specifically, where 
the cylinder boundaries are. This allows the filesystem's smart block allocation strategy to work. 



pb_Environment [17] 



environment vector for this partition 
containing: 



de_TableSize 

de_SizeBlock 

de_SecOrg 

de_Surf aces 

de SectorPerBlock 



size of Environment vector 

== 128 (for 512 bytes/logical block) 

= = 

number of heads (see layout discussion) 

= = 1 



de_BlocksPerTrack blocks per track (see layout discussion) 



de Reserved 



DOS reserved blocks at start of partition. 
Must be >= 1 . 2 is recommended. 



de PreAlloc 



DOS reserved blocks at end of partition 
Valid only for filesystem type DOS^A (the 
fast file system) . Zero otherwise. 



de Interleave 



DOS interleave 

Valid only for filesystem type DOS' 

old file system) . Zero otherwise. 



(the 



de_LowCyl 



starting cylinder 



de_HighCyl 
de NumBuffers 



de_BufMemType 



de MaxTransfer 



de Mask 



de BootPri 



de_DosType 



pb_EReserved [15] 
FileSysHeaderBlock 
The current specification for the FileSysHeaderBlock follows 



max cylinder 

initial # DOS of buffers. 
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type of mem to allocate for buffers 
The second argument to AllocMemO . 

max number of bytes to transfer at a time. 
Drivers should be written to handle requests 
of any length. 

address mask to block out certain memory 
Normally $00ffffff for DMA devices. 

Boot priority for autoboot 

Suggested value: zero. Keep less than 

five, so it won't override a boot floppy. 

ASCII string showing filesystem type; 
DOS"® ($444F5300) is old filesystem, 
DOS'A ($444F5301) is fast file system. 
UNI<anything> is a Unix partition. 

reserved for future environment vector 



fhb_ID 

fhb_SummedLongs 

fhb_ChkSum 

fhb HostID 



== 'FSHD' 

= = 64 

block checksum (longword sum to zero) 

SCSI Target ID of host 

This describes the initiator ID for the 

creator of this block. (see rdb_HostID 

discussion) 



fhb_Next 

fhb_Flags 

fhb Reservedl [2] 



block number of next FileSysHeaderBlock 
see below for defines 
set to zero 



The following information is used to construct a FileSysEntry node in the FileSystem. resource. 



fhb_DosType 



fhb Version 



fhb_PatchFlags 



fhb_Type 

fhb_Task 

fhb_Lock 

fhb_Handler 

fhb_StackSize 

fhb_Priority 



file system description 

This is matched with a partition environment's 

de_DosType entry. 

release version of this load image 
Usually MSW is version, LSW is revision. 

patch flags 

These are bits set for those of the following 
that need to be substituted into a standard 
device node for this file system, lsb first : 
e.g. 0x180 to substitute SegList & GlobalVec 

device node type: zero 

standard dos "task" field: zero 

not used for devices : zero 

filename to loadseg: zero placeholder 

stacksize to use when starting task 

task priority when starting task 



fhb_Startup 
fhb_SegListBlocks 



startup msg : zero placeholder 

first of linked list of LoadSegBlocks : 
Note that if the f hb_PatchFlags bit for this 
entry is set (bit 7) , the blocks pointed to by 
this entry must be LoadSeg'd and the resulting 
BPTR put in the FileSysEntry node. 



fhb GlobalVec 



BCPL global vector when starting task 
Zero or -1. 



fhb_Reserved2 [23] 
fhb Reserved3 [21] 



LoadSegBlock 



(those reserved by PatchFlags) 
set to zero 

774 Amiga ROM Kernel Reference Manual: Libraries 



This is the current specification of the LoadSegBlock. The end of data occurs when lsb_Next is NULL 

($FFFFFFFF), and the summed data is exhausted. 



lsb ID 



'LSEG' 



lsb_SummedLongs 



size of this checksummed structure 
Note that this is not 64 like most of the other 
structures. This is the number of valid longs 
in this image, like bbb_SummedLongs . 



lsb_ChkSum 
lsb HostID 



block checksum (longword sum to zero) 

SCSI Target ID of host 

This describes the initiator ID for the creator 

of these blocks. (see rdb HostID discussion) 



lsb Next 



block number of the next LoadSegBlock 



lsb LoadData 



filesysres.h and .;' 



data for "loadseg" 

The data starts here and continues as long 
as indicated by lsb_SummedLongs-5 : e.g. If 
lsb_SummedLongs is 128 (ie. for 512 byte 
blocks) , 123 longs of data are valid here. 



The FileSysResource is created by the first code that needs to use it. It is added to the resource list for others to 
use. (Checking and creation should be performed while Forbid() is in effect). Under Release 2 the resource is 
created by the system early on in the initialization sequence. Under 1 .3 it is the responsibility of the first RDB 
driver to create it. 

FileSysResource 



f sr_Node 

f sr_Creator 

f sr_FileSysEntries 



on resource list with the name FileSystem. resource 
name of creator of this resource 
list of FileSysEntry structs 



FileSysEntry 
f se_Node 

f se_DosType 
fse Version 



on f sr_FileSysEntries list 

ln_Name is of creator of this entry 

DosType of this FileSys 

release version of this FileSys 

Usually MSW is version, LSW is revision. 



f se_PatchFlags 



bits set for those of the following that 
need to be substituted into a standard 



device node for this file system: e.g. 
$180 for substitute SegList & GlobalVec 



f se_Type 
fse_Task 
f se_Lock 
f se_Handler 
f se_StackSize 
f se_Priority 
f se_Startup 
f se_SegList 
fse GlobalVec 



device node type: zero 
standard dos "task" field 
not used for devices : zero 
filename to loadseg (if SegList is null) 
stacksize to use when starting task 
task priority when starting task 
startup msg : FileSysStartupMsg for disks 
segment of code to run to start new task 
BCPL global vector when starting task 



No more entries need exist than those implied by f se_PatchFlags, so 
entries do not have a fixed size. 

Expansion Library 775 

For additional information on initializing and booting a Rigid Disk Block filesystem device, see the SCSI Device 
chapter of the Addison-Wesley Amiga ROM Kernel Reference Manual: Devices. Writers of drivers for expansion 
devices that perform their own DMA (direct memory access) should consult the Exec chapters and Autodocs for 
information on Release 2 processor cache control functions including CachePreDMA() and CachePostDMA(). 
See the following include files for additional notes and related structures: <libraries/configvers.h> and <./>, 
<libraries/configregs.h> and <./>, <devices/hardblocks.h> and <./>, <resources/filesysres.h> and <./>, and 
<libraries/filehandler.h> and <./>. 



Function Reference 



The following are brief descriptions of the expansion library functions that are useful for expansion device drivers 
and related applications. See the Amiga ROM Kernel Reference Manual: Includes and Autodocs for the complete 
descriptions of all the expansion library functions. 

Table 32-2: Expansion Library Functions 



Function 
RnaConflgDevTj 



Description 

Returns a pointer to the Contiguevstructure ot a given expansion device. 



MakeDosNode() 

AddDosNode() 

AddBootNodeQ 



Creates the DOS device node for disk and similar expansion devices. 

Adds a DOS device node to the system. 

Adds an autobooting DOS device node to the system (V36). 



tjetuurrentbinding() 
SetCurrentBinding() 
ObtainConfigBindingO 
ReleaseConfigBinding() 



bfeturns a pointer to the uurrentbindmg structure ot a given device. 
Set up for reading the CurrentBinding with GetCurrentBinding(). 
Protect the ConfigDev structure with a semaphore. 
Release a semaphore on ConfigDev set up with ObtainCurrentBindingQ 
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Chapter 33 
IFFParse Library 



The iffparse. library was created to help simplify the job of parsing IFF files. Unlike other IFF libraries, 
iffparse. library is not form-specific. This means that the job of interpreting the structure and contents of the IFF file 
is up to you. Previous IFF file parsers were either simple but not general, or general but not simple. IFFParse 
tries to be both simple and general. 



The Structure of IFF Files 



Many people have a misconception that IFF means image files. This is not the case. IFF (short for Interchange 
File Format) is a method of portably storing structured information in machine-readable form. The actual 
information can be anything, but the manner in which it is stored is very specifically detailed. This specification is 
the IFF standard. 

The IFF standard was originally designed in 1985 by Electronic Arts in conjunction with a committee of 
developers. The full standard along with file descriptions and sample code is published in the Amiga ROM Kernel 
Reference Manual: Devices (3rd edition). 

The goal of the IFF standard is to allow customers to move their own data between independently developed 
software products. The types of data objects to exchange are open-ended and currently include plain and 
formatted text, raster and structured graphics, fonts, music, sound effects, musical instrument descriptions, and 
animation. IFF addresses these needs by defining a standard for self-identifying file structures and rules for 
accessing these files. 

Chunks: The Building Blocks of IFF 

IFF files contain various types and amounts of data grouped in data chunks, each starting with a four-letter ASCII 
identifier (the chunk ID) followed by a 32-bit length count (the chunk size). The identifier and length count make it 
possible for IFF readers to skip over chunks that they don't understand or don't care about, and extract only the 
information they need. It may be helpful to think of these chunks as the building blocks of an IFF file (Figure 
33-1). 
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Figure 33-1 : The Chunk - The Building Block of IFF 



'CKID' Size 

data data data data 
data data data data 
data data data . . . 



The 'CKID' (chunk ID) characters of a real chunk will be a four letter identifier such as 'BODY' or 'CMAP', 
specifying the type and format of data stored in the chunk. Most chunks contain a simple defined grouping of 
byte, word, and long variables similar to the contents of a C structure. Others such as sound sample and bitmap 
image body chunks, contain a stream of compressed data. 

Chunk writing is fairly straightforward with the one caveat that all chunks must be word-aligned. Therefore an 
odd-length chunk must be followed by a pad byte of zero (which is not counted in the size of the chunk). When 
chunks are nested, the enclosing chunk must state the total size of its composite contents (including any pad 
bytes). 

About Chunk Length. Every IFF data chunk begins with a 4-character identifier field 
followed by a 32-bit size field (these 8 bytes are sometimes referred to as the chunk header). 



The size field is a count of the rest of the data bytes in the chunk, not including any pad byte. 
Hence, the total space occupied by a chunk is given by its size field (rounded to the nearest 
even number) + 8 bytes for the chunk header. 

Composite Data Types 

Standard IFF files generally contain a variable number of chunks within one of the standard IFF composite data 
types (which may be thought of as chunks which contain other chunks). The IFF specification defines three basic 
composite data types, 'FORM', 'CAT ', and 'LIST'. A special composite data type, the 'PROP', is found only 
inside a LIST. 

Table 33-1 : Usage of Composite IFF Types 

FORM A grouping of chunks which describe one set of data 

LIST A grouping of the same type of FORMs with shared properties in a PROP 

PROP May appear in a LIST to define chunks shared by several FORMs 

CAT A concatenation of related FORMs or LISTs 

The special IFF composite data types, like simple chunks, start with a 4-character identifier (such as 'FORM'), 
followed by a 32-bit length. But their data begins with a second 4-character identifier that tells you what type of 
data is in the composite. For example, a FORM ILBM contains chunks describing a bitmap image, and a FORM 
FTXT contains chunks describing formatted text. 

It may help to think of each composite data type as a box containing chunks, the IFF building blocks. Figure 33-2 
shows a diagram of a typical composite. 
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Figure 33-2: The FORM - The Most Common IFF File Type 



'FORM' Size 'NAME' 



l CKID' Size 
data data data 
data data . . . 



'CKID' Size 
data data data 
data data . . . 



'CKID' Size 
data data data 
data data . . . 



The example FORM in figure 33-2 is outlined below showing the size of chunks within the FORM. Notice that the 
size of a composite includes its second 4-character identifier (shown below as 'NAME'). 



.FORM 72 NAME 
..CKID22 
..CKID10 
..CKID12 



(72 is the size of the FORM starting with the "N" of NAME) 
(then 22 bytes of data, so chunk header + chunk size is 30) 
(then 1 bytes of data, so chunk header + chunk size is 1 8) 
(then 12 bytes of data, so chunk header + chunk size is 20) 



Note: In the example above, indentation represents the nesting of the chunks within the 
FORM. Real FORMs and chunks would have different four-character identifiers rather than 
'NAME' and 'CKID': 



Any odd-length chunks must have a pad byte of zero at the end of the chunk. As shown below, this pad byte is 
not counted in the size of the chunk but is counted in the size of any composite types (such as FORM) that 
contain an odd-length chunk. 

Warning: some IFF readers and writers do not deal with this properly. 

.FORM 72 NAME (72 is the size of the FORM starting with the "N" of NAME) 

..CKID 21 (then 21 bytes of data, so chunk header + chunk size is 29) 

..0 (pad byte of zero, size 1) 

..CKID 10 (then 10 bytes of data, so chunk header + chunk size is 18) 

..CKID 12 (then 12 bytes of data, so chunk header + chunk size is 20) 

Most IFF files are of the composite type FORM. Generally, a FORM is a simple grouping of chunks that provide 
information about some data, and the data itself. Although some standard chunks have common usage within 
different FORMS, the identity and format of most chunks within a FORM are relative to the definition and 
specification of the FORM. For example, a CRNG chunk in a FORM ILBM may have a totally different format and 
contents than a chunk named CRNG in a different type of FORM. 

One of the most popular IFF FORMs that has been defined is the ILBM standard. This is how most Amiga bitmap 
imagery is stored. Since this is the most common IFF file, it is used frequently as an example. 
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Here is the output of a program called Sift.c that displays a text description of the contents of an IFF file (Sift.c is 
listed at the end of this chapter). The file shown below is a fairly simple ILBM. 

.FORM 11068 ILBM 
..BMHD20 
..CAMG 4 
..CMAP12 
..BODY 10995 

Computing the Size of a FORM. The size of the FORM (1 1068 bytes) is equal to the sum of 
the sizes stated in each chunk contained within the FORM, plus 8 bytes for the overhead of 
each chunk header (4 bytes for the 4-character chunk ID, and 4 bytes for the 32-bit chunk 
size), plus 4 bytes for the FORM'S own 4-character ID ('ILBM'), plus 1 byte more for each pad 
byte that follow any odd-length chunks. 



Parsing an IFF File 



Chunk reading requires a parser to scan each chunk and dispatch the proper access/conversion procedure. For 
a simple IFF file, such parsing may be relatively easy, consisting mainly reading in the data of desired chunks, 
and seeking over unwanted chunks (and the pad byte after odd-length chunks). Interpreting nested chunks is 
more complex, and requires a method for keeping track of the current context, i.e., the data which is still relevant 
at any particular depth into the nest. The original IFF specifications compare an IFF file to a C program. Such a 
metaphor can be useful in understanding the scope of of the chunks in an IFF file. 

The IFFParse library addresses general IFF parsing requirements by providing a run-time library which can 
extract the chunks you want from an IFF file, with the ability to pass control to you when it reaches a chunk that 
requires special processing such as decompression. IFFParse also understands complex nested IFF formats and 
will keep track of the context for you. 

Basic Functions and Structures of IFFParse Library 

The structures and flags of the IFFParse library are defined in the include files <librahes/iffparse.h> and 
<libraries/iff parse. i>. IFF files are manipulated through a structure called an IFFHandle. Only some of the fields 
in the IFFHandle are publicly documented. The rest are managed internally by IFFParse. This handle is passed 
to all IFFParse functions, and contains the current parse state and position in the file. An IFFHandle is obtained 
by calling AlloclFF(), and freed through FreelFFQ. This is the only legal way to obtain and dispose of an 
IFFHandle. 

The public portion of if IFFHandle is defined as follows: 



/* 

* Structure associated with an active IFF stream. 

* "iff_Stream" is a value used by the client's read/write/seek 

* functions - it will not be accessed by the library itself and 

* can have any value (could even be a pointer or a BPTR) . 

*/ 

struct IFFHandle { 

ULONG iff_Stream; 

ULONG iff_Flags; 

LONG iff_Depth; /* Depth of context stack. */ 

/* There are private fields hiding here. */ 
} ; 
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Stream Management 

A stream is a linear array of bytes that may be accessed sequentially or randomly. DOS files are streams. 
IFFParse uses Release 2 Hook structures (defined in <utility/hooks.h>) to implement a general stream 
management facility. This allows the IFFParse library to read, write, and seek any type of file handle or device by 
using an application-provided hook function to open, read, write, seek and close the stream. 

Built on top of this facility, IFFParse has two internal stream managers: one for unbuffered DOS files (AmigaDOS 
filehandles), and one for the Clipboard. 

Initialization 

As shown above, the IFFHandle structure contains the public field iff_Stream. This is a longword that must be 
initialized to contain something meaningful to the stream manager. IFFParse never looks at this field itself (at 
least not directly). Your iff_Stream may be an AmigaDOS filehandle, or an IFFParse ClipboardHandle, or a 
custom stream of any type if you provide your own custom stream handler (see the section on "Custom Stream 
Handlers" later in this chapter). You must initialize your IFFHandle structure's iff_Stream to your stream, and 
then initialize the IFFHandle's flags and stream hook. 

Three sample initializations are shown here. In the case of the internal DOS stream manager, iff_Stream is an 
AmigaDOS filehandle as returned by Open(): 

iff->if f_Stream = (ULONG) Open ("filename", MODE_OLDFILE) ; 

if (if f ->if f_Stream) InitlFFasDOS (iff); /* use internal DOS stream manager */ 

In the case of the internal Clipboard stream manager, iff_Stream is a pointer to an IFFParse ClipboardHandle 
structure (the OpenClipboard() call used here is a function of iffparse. library, not the clipboard.device): 

iff->if f_Stream = (ULONG) OpenClipboard (PRIMARY_CLIP) ; 
InitlFFasClip (iff) ; /* use internal Clipboard stream manager */ 

When using a custom handle such as an fopenQ file handle, or a device other than the clipboard, you must 
provide your own flags and stream handler: 

iff->if f_Stream = (ULONG) OpenMyCustomStream ( "f oo" ) ; 
InitlFF (iff, IFFF_FSEEK | IFFF_RSEEK, kmystreamhook) ; 

IFFParse "knows" the seek capabilities of DOS and ClipboardHandle streams, so lnitlFFasDOS() and 
InitlFFasClipO set the flags for you. 

You May Change the Seek Bits in iff_Flags: IFFParse sets IFFF_FSEEK | IFFF_RSEEK for 
DOS files. This is not always true (e.g., pipes). If you know that a DOS file has different 
seek characteristics, your application may correct the seek bits in iff_Flags after calling 
InitlFFasDOSf). 
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When using InitlFFQ to provide a custom handler, you must also provide flags to tell IFFParse the capabilities of 



your stream. The flags are: 

IFFF_FSEEK: This stream has forward-seek capability only. 

IFFFRSEEK: This stream has random-seek capability. IFFFRSEEK tends to imply 

IFFF_FSEEK, but it's best to specify both. 

If neither flag is specified, you're telling IFFParse that it can't seek through the stream. 

After your stream is initialized, call OpenlFF(): 

error = OpenlFF (iff, IFFF_READ) ; 

Once you establish a read/write mode (by passing IFFF_READ or IFFF_WRITE), you remain in that mode until 
you call CloselFF(). 

Termination 

Termination is simple. Just call CloselFF(iff). This may be called at any time, and terminates IFFParse's 
transaction with the stream. The stream itself is not closed. The IFFHandle may be reused; you may safely call 
OpenlFF() on it again. You are responsible for closing the streams you opened. A stream used in an IFFHandle 
must generally remain open until you CloselFF(). 

Custom Streams 

A custom stream handler can allow you (and iffparse. library) to use your compiler's own file I/O functions such as 
fopen(), freadQ and fwrite(), rather than the lower-level AmigaDOS equivalents Open(), Read(), and Write(). A 
custom stream handler could also be used to read or write IFF files from an Exec device or an unusual handler or 
filesystem. 

If you install your own stream handler function, iffparse. library will call your function whenever it needs to read, 
write, or seek on your file. Your stream handler function will then perform these stream actions for iffparse. library. 
See the "Custom Stream Handlers" section for more information on custom stream handlers. 



Parsing 



This is both simple and complicated. It's simple in that it's just one call. It's complicated in that you have to seize 
control of the parser to get your data. 

The parser operates automatically, scanning the file, verifying syntax and layout rules. If left to its default 
behavior, it will scan through the entire file until it reaches the end, whereupon it will tell you that it got to the end. 

The whole scanning procedure is controlled through one call: 

error = ParselFF (iff, controlmode) ; 

The control modes are IFFPARSE_SCAN, IFFPARSE_STEP and IFFPARSE_RAWSTEP. For now, only the 
IFFPARSESCAN control mode is considered. 
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Controlling Parsing 

ParselFF(), if left to itself, wouldn't do anything useful. Ideally, it should stop at strategic places so we can look at 
the chunks. Here's where it can get complicated. 

There are many functions provided to help control the parsing process; only the common ones are covered here. 
Additional functions are described in the Autodocs for iffparse. library (for the complete Autodocs, refer to the 
Amiga ROM Kernel Reference Manual: Includes and Autodocs also by Addison-Wesley). 

StopChunk() 

You can instruct the parser to stop when it encounters a specific IFF chunk by using the function StopChunkQ: 



error = StopChunk (iff, ID_ILBM, ID_BODY) ; 

When the parser encounters the requested chunk, parsing will stop, and ParselFF() will return the value zero. 
The stream will be positioned ready to read the first data byte in the chunk. You may then call 
ReadChunkBytesQ or ReadChunkRecordsQ to pull the data out of the chunk. 

You may call StopChunk() any number of times for any number of different chunk types. If you wish to identify 
the chunk on which you've stopped, you may call CurrentChunk() to get a pointer to the current ContextNode, 
and examine the cn_Type and cn_ID fields. 

Using StopChunk() for every chunk, you can parse IFF files in a manner very similar to the way you're probably 
doing it now, using a state machine. However, this would be a terrible underuse of IFFParse. 

PropChunk()/FindProp() 

In the case of a FORM ILBM, certain chunks are defined as being able to appear in any order. Among these are 
the BMHD, CMAP, and CAMG. Typically, BMHD appears first, followed by CMAP and CAMG, but you can't make 
this assumption. The IFF and ILBM standards require you to assume these chunks will appear in any order. So 
ideally, what you'd like to do is collect them as they arrive, but not do anything with them until you actually need 
them. 

This is where PropChunk() comes in. The syntax for PropChunk() is identical to StopChunkQ: 

error = PropChunk (iff, ID_ILBM, ID_BMHD) ; 

When you call ParselFF(), the parser will look for chunks declared with PropChunk(). When it sees them, the 
parser will internally copy the contents of the chunk into memory for you before continuing its parsing. 

When you're ready to examine the contents of the chunk, you use the function FindProp(): 

StoredProperty = FindProp (iff, ID_ILBM, ID_BMHD) ; 
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FindProp() returns a pointer to a struct StoredProperty, which contains the chunk size and data. If the chunk 
was never encountered, NULL is returned. This permits you to process the property chunks in any order you 
wish, regardless of how they appeared in the file. This provides much better control of data interpretation and 
also reduces headaches. The following fragment shows how ILBM BitMapHeader data could be accessed after 
using ParselFF() with PropChunk(iff, IDJLBM, ID_BMHD): 

struct StoredProperty *sp; /* defined in iff parse. h */ 
struct BitMapHeader *bmhd; /* defined in IFF spec */ 

if (sp = FindPropfif f , ID_ILBM, ID_BMHD) ) 

{ 

/* If property is BMHD, sp->sp_Data is ptr to data in BMHD */ 

bmhd = (struct BitMapHeader *) sp->sp_Data; 

printf ("BMHD: PageWidth = %ld\n" , bmhd->PageWidth) ; 

} 

Putting it Together 

With just StopChunkQ, PropChunk(), and ParselFF(), you can write a viable ILBM display program. Since 
IFFParse knows all about IFF structure and scoping, such a display program would have the added ability to 
parse complex FORMs, LISTs, and CATs and attempt to find imagery buried within. 

Such an ILBM reader might appear as follows: 

iff = AllocIFFf) ; 

iff->if f_Stream = Open ("shuttle dog", MODE_OLDFILE) ; 

InitlFFasDOS (iff) ; 

OpenlFF (iff, IFFF_READ) ; 

PropChunk (iff, ID_ILBM, ID_BMHD) ; 



PropChunk (iff, ID_ILBM, ID_CMAP) ; 
PropChunk (iff, ID_ILBM, ID_CAMG) ; 
StopChunk (iff, ID_ILBM, ID_BODY) ; 
ParselFF (iff, IFFPARSE_SCAN) ; 

if (bmhdprop = FindProp (iff, ID_ILBM, ID_BMHD) ) 

conf igurescreen (bmhdprop) ; 
else 

bye ("No BMHD, no picture."); 

if (cmapprop = FindProp (iff, ID_ILBM, ID_CMAP) ) 

setcolors (cmapprop) ; 
else 

usedef aultcolors (); 

if (camgprop = FindProp (iff, ID_ILBM, ID_CAMG) ) 
setdisplaymodes (camgprop) ; 

decodebody (iff) ; 
showpicture () ; 
CloselFF (iff) ; 
Close (if f->iff_Stream) ; 
FreelFF (iff) ; 

Open the Library. Application programs must always open iffparse. library before using the 
functions outlined above. 

Only Example Programs Skip Error Checking. Error checking is not used in the example 
above for the sake of clarity. A real application should always check for errors. 
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Other Chunk Management Functions 

Several other functions are available for controlling the parser. 

CollectionChunk() and FindCollectionQ 

PropChunk() keeps only one copy of the declared chunk (the one currently in scope). CollectionChunk() 
collects and keeps all instances of a specified chunk. This is useful for chunks such as the ILBM CRNG chunk, 
which can appear multiple times in a FORM, and which don't override previous instances of themselves. 
CollectionChunk() is called identically to PropChunk(): 

error = CollectionChunk (iff, type, id); 

When you wish to find the collected chunks currently in scope, you use the function FindCollection(): 

ci = FindCollection (iff, type, id); 

You will be returned a pointer to a Collectionltem, which is part of a singly-linked list of all copies of the specified 
chunk collected so far that are currently in scope. 

struct Collectionltem { 

struct Collectionltem *ci_Next; 

LONG ci_Size; 

UBYTE *ci_Data; 

}; 

The size of this copy of the chunk is in the Collectionltem's ci_Size field. The ci_Data field points to the chunk 
data itself. The ci_Next field points to the next Collectionltem in the list. The last element in the list has ci_Next 
set to NULL. 

The most recently-encountered instance of the chunk will be first in the list, followed by earlier chunks. Some 
might consider this ordering backwards. 



If NULL is returned, the specified chunk was never encountered. 

StopOnExit() 

Whereas StopChunk() will stop the parser just as it enters the declared chunk, StopOnExit() will stop just before 
it leaves the chunk. This is useful for finding the end of FORMs, which would indicate that you've collected all 
possible data in this FORM and may now act on it. 

/* Ask ParselFFO to stop with IFFERR_EOC when leaving a FORM ILBM */ 
StopOnExit (if f , ID_ILBM, ID_FORM) ; 

EntryHandlerQ 

This is used to install your own custom chunk entry handler. See the "Custom Chunk Handlers" section below for 
more information. StopChunkQ, PropChunk(), and CollectionChunk() are internally built on top of this. 
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ExitHandlerQ 

This is used to install your own custom chunk exit handler. See the "Custom Chunk Handlers" section below for 
more information. StopOnExit() is internally built on top of this. 

Reading Chunk Data 

To read data from a chunk, use the functions ReadChunkBytesQ and ReadChunkRecords(). Both calls 
truncate attempts to read past the end of a chunk. For odd-length chunks, the parser will skip over the pad bytes 
for you. Remember that for chunks which have been gathered using PropChunk() (or CollectionChunk() ), you 
may directly reference the data by using FindProp() (or FindCollectionQ ) to get a pointer to the data. 
ReadChunkBytesQ is commonly used when loading and decompressing bitmap and sound sample data or 
sequentially reading in data chunks such as FTXT CHRS text chunks. See the code listing ClipFTXT.c for an 
example usage of ReadChunkBytes(). 

Other Parsing Modes 

In addition to the mode IFFPARSE_SCAN, there are the modes IFFPARSE_STEP and IFFPARSE_RAWSTEP. 

IFFPARSE_RA WSTEP 

This mode causes the parser to progress through the stream step by step, rather than in the automated fashion 
provided by IFFPARSE_SCAN. In this mode, ParselFF() will return upon every entry to and departure from a 
context. 

When the parser enters a context, ParselFFQ will return zero. CurrentChunk() will report the type and ID of the 
chunk just entered, and the stream will be positioned to read the first byte in the chunk. When entering a FORM, 
LIST, CAT or PROP chunk, the longword containing the type (e.g., ILBM, FTXT, etc.) is read by the parser. In 
this case, the stream will be positioned to read the byte immediately following the type.) 

When the parser leaves a context, ParselFF() will return the value IFFERR_EOC. This is not strictly an error, but 
an indication that you are about to leave the current context. CurrentChunk() will report the type and ID of the 
chunk you are about to leave. The stream is not positioned predictably within the chunk. 

The parser does not call any installed chunk handlers when using this mode (e.g., property chunks declared with 
PropChunk() will not be collected). 

See the example program, Sift.c, for a demonstration of IFFPARSERAWSTEP. 

IFFPARSE_STEP 

This mode is identical to IFFPARSE_RAWSTEP, except that, before control returns to your code, the chunk 
handler (if any) for the chunk is invoked. 
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Writing IFF Files 



IFFParse provides facilities for writing IFF files. Again, IFFParse makes no assumptions about the data you're 
writing, and concerns itself with verifying the syntax of your output. 

Creating Chunks In a File 

Because the IFF specification has nesting and scoping rules, you can nest chunks inside one another. One 
instance is the BMHD chunk, which is commonly nested inside a FORM chunk. Thus, it is necessary for you to 
inform IFFParse when you are starting and ending chunks. 

PushChunkQ 

To tell IFFParse you are about to begin writing a new chunk, you use the function PushChunkQ: 

error = PushChunk (iff, ID_ILBM, ID_BMHD, chunks ize) ; 

The chunk ID and size are written to the stream. IFFParse will enforce the chunk size you specified; attempts to 
write past the end of the chunk will be truncated. If, as a chunk size argument, you pass IFFSIZEJJNKNOWN, 
the chunk will be expanded in size as you write data to it. 

PopChunkQ 

When you are through writing data to a chunk, you complete the write by calling PopChunk(): 

error = PopChunk (iff) ; 

If you wrote fewer bytes than you declared with PushChunk(), PopChunk() will return an error. If you specified 
IFFSIZE_UNKNOWN, PopChunk() will seek backward on the stream and write the final size. If you specified a 
chunk size that was odd, PopChunk() will write the pad byte automatically. 

PushChunk() and PopChunk() nest; every call to PushChunk() must have a corresponding call to PopChunk(). 

Writing Chunk Data 

Writing the IFF chunk data is done with either the WriteChunkBytes() or WriteChunkRecords() functions. 

error = WriteChunkBytes (iff, buf, size); 

error = WriteChunkRecords (iff, buf, recsize, numrec) ; 

If you specified a valid chunk size when you called PushChunk( ) , WriteChunkBytesQ and 
WriteChunkRecords() will truncate attempts to write past the end of the chunk. 
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Code to write an ILBM file might take the following form: 

iff = AllocIFF () ; 

iff->iff_Stream = Open ("foo", MODE_NEWFILE) ; 

InitlFFasDOS (iff) ; 

OpenlFF (iff, IFFF_WRITE) ; 

PushChunk (iff, ID_ILBM, ID_FORM, IFFSIZEJJNKNOWN) ; 

PushChunk (iff, ID_ILBM, ID_BMHD, sizeof (struct BitMapHeader) ) ; 
WriteChunkBytes (iff, &bmhd, sizeof (bmhd) ) ; 
PopChunk (iff) ; 

PushChunk (iff, ID_ILBM, ID_CMAP, cmapsize) ; 
WriteChunkBytes (iff, cmapdata, cmapsize); 
PopChunk (iff) ; 



PushChunk (iff, ID_ILBM, ID_BODY, IFFSIZE_UNKNOWN) ; 
packwritebody (iff) ; 
PopChunk (iff) ; 

PopChunk (iff) ; 

CloselFF (iff) ; 

Close (if f ->if f_Stream) ; 

FreelFF (iff) ; 

Again, error checking is not present for clarity. See the example code ClipFTXT.c which writes a simple FTXT clip 
to the clipboard. 

A Note on Seekability 

As you can see from the above examples, IFFParse works best with a stream that can seek randomly. However, 
it is not possible to seek on some streams (e.g., pipes). 

IFFParse will read and write streams with limited or no seek capability. In the case of reading, only forward-seek 
capability is desirable. Failing this, IFFParse will fake forward seeks with a number of short reads. 

In the case of writing, if the stream lacks random seek capability, IFFParse will buffer the entire contents of the file 
until you do the final PopChunkQ, or when you CloselFF() the handle. At that time, the entire stream will be 
written in one go. This buffering happens whether or not you specify all the chunk sizes to PushChunk(). 

About the Internal Buffering. The current implementation of this internal buffering could be 
more efficient. Be aware that Commodore reserves the right to alter this behavior of the 
parser, to improve performance or reduce memory requirements. We mention this behavior 
on the off chance it is important to you. 
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Context Functions 

Internally, IFFParse maintains IFF nesting and scoping context via a context stack. The PushChunkQ and 
PopChunk() functions get their names from this basic idea of the iffparse. library. Direct access to this stack is not 
allowed. However, many functions are provided to assist in examining and manipulating the context stack. 

About the Context Stack. It is probably easier to think of a stack of blocks on a table in front of 
you when reading this discussion. 

As the nesting level increases (as would happen when parsing a nested LIST or FORM), the depth of the context 
stack increases; new elements are added to the top. When these contexts expire, the ContextNodes are deleted 
and the stack shrinks. 

Context Nodes 

The current context is said to be the top element on the stack. Contextual information is stored in a structure 
called a ContextNode: 



struct ContextNode { 






struct 


MinNode 


en Node ; 




LONG 




en ID; 




LONG 




en Type ; 




LONG 




en Size; 


/ 


LONG 




en Scan; 


/ 



Size of this chunk */ 

# of bytes read/written so far */ 
/* There are private fields hiding here. */ 



CurrentChunk() 

You can obtain a pointer to the current ContextNode through the function CurrentChunkQ: 



currentnode = CurrentChunk (iff) ; 

The ContextNode tells you the type, ID, and size of the currently active chunk. If there is no currently active 
context, NULL is returned. 

ParentChunkQ 

To find the parent of a context, you call ParentChunk() on the relevant ContextNode: 

parentnode = Parent Chunk (currentnode) ; 
If there is no parent context, NULL is returned. 

The Default Context 

When you first obtain an IFFHandle through AlloclFF(), a hidden default context node is created. You cannot get 
direct access to this node through CurrentChunkQ or ParentChunk(). However, using StoreLocalltemQ, you 
can store information in this context. 
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Context-Specific Data: LocalContextltems 

ContextNodes can contain application data specific to that context. These data objects are called 
LocalContextltems. LocalContextltems (LCIs) are a grey-box structure which contain a type, ID and 
identification field. LCIs are used to store context-sensitive data. The format of this data is application-defined. A 
ContextNode can contain as many LCIs as you want. 
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Figure 33-3: IFFParse Context Stack 

Figure 33-3 shows the relationship between the IFFHandle, the ContextNodes, and the LCIs. The IFFHandle is 
the root of the tree, so to speak. ContextNodes "grow" out of the IFFHandle. In turn, LCIs "grow" out of the 
ContextNodes. What grows out of an LCI is client-defined. 



AllocLocalltemQ 

To create an LCI, you use the function AllocLocalltem(): 

lei = AllocLocalltem (type, id, ident, datasize); 

If successful, you will be returned a pointer to an LCI having the specified type, ID, and identification values; and 
with datasize bytes of buffer space for your application to use. 

LocalltemDataQ 

To get a pointer to an LCIs data buffer, you use Local Item Data(): 

buf = LocalltemData (lei) ; 

You may read and write the buffer to your heart's content; it is yours. You should not, however, write beyond the 
end of the buffer. The size of the buffer is what you asked for when you called AllocLocalltem() 
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Storing LCIs 

Once you've created and initialized an LCI, you'll want to attach it to a ContextNode. Though a ContextNode 
can have many LCIs, a given LCI can be linked to only one ContextNode. Once linked, an LCI cannot be 
removed from a ContextNode (this may change in the future). Storing an LCI in a ContextNode is done with the 
functions StoreLocalltem() and StoreltemlnContext(). 

StoreLocalltemQ 

The StoreLocalltem() function is called as follows: 

error = StoreLocalltem (iff, lei, position); 

The position argument determines where the LCI is stored. The possible values are IFFSLI_ROOT, IFFSLI_TOP, 
and IFFSLI_PROP. 

IFFSLIROOT causes StoreLocalltem() to store your LCI in the default ContextNode. 

IFFSLITOP gets your LCI stored in the top (current) ContextNode. 

The LCI Ends When the Current Context Ends. When the current context expires, your LCI 
will be deleted by the parser. 

IFFSLI_PROP causes your LCI to be stored in the topmost context from which a property would apply. This is 
usually the topmost FORM or LIST chunk. For example, suppose you had a deeply nested ILBM FORM, and you 
wanted to store the BMHD property in its correct context such that, when the current FORM context expired, the 
BMHD property would be deleted. IFFSLI_PROP will cause StoreLocalltem() to locate the proper context for 
such scoping, and store the LCI there. See the section on "Finding the Prop Context" for additional information 
on the scope of properties. 

StoreltemlnContextQ 

StoreltemlnContext() is used when you already have a pointer to the ContextNode to which you want to attach 
your LCI. It is called like so: 

StoreltemlnContext (iff, lei, contextnode) ; 

StoreltemlnContext() links your LCI into the specified ContextNode. Then it searches the ContextNode to see 
if there is another LCI with the same type, ID, and identification values. If so, the old one is deleted. 

FlndLocalltemQ 

After you've stored your LCI in a ContextNode, you will no doubt want to be able to find it again later. You do 
this with the function FindLocalltem(), which is called as follows: 



lei = FindLocalltem (iff, type, id, ident) ; 

FindLocalltem() attempts to locate an LCI having the specified type, ID, and identification values. The search 
proceeds as follows (refer to Figure 33-3 to understand this better). 
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FindLocalltem() starts at the top (current) ContextNode and searches all LCIs in that context. If no matching 
LCIs are found, it proceeds down the context stack to the next ContextNode and searches all its LCIs. The 
process repeats until it finds the desired LCI (whereupon it returns a pointer to it), or reaches the end without 
finding anything (where it returns NULL). 

Context Stack Position. LCIs higher in the stack will "override" lower LCIs with the same type, 
ID, and identification field. This is how property scoping is handled. As ContextNodes are 
popped off the context stack, all its LCIs are deleted as well. See the section on "Freeing 
LCIs" below for additional information on deleting LCIs. 

Some Interesting Internal Details 

l/Mfi/V/A/G.'This section details some internal implementation details of iffparse. library which 
may help you to understand it better. Use of the following information to do "clever" things in 
an application is forbidden and unsupportable. Don't even think about it. 

It turns out that StoredProperties, Collectionltems, and entry and exit handlers are all implemented using LCIs. 
For example, when you call FindPropQ, you are actually calling a front-end to FindLocalltem(). The mysterious 
identification value (which has heretofore never been discussed) is a value which permits you to differentiate 
between LCIs having the same type and ID. 

For instance, suppose you called PropChunk(), asking it to store an ILBM BMHD. PropChunk() will install an 
entry handler in the form of an LCI, having type equal to 'ILBM', ID equal to 'BMHD', and an identification value of 
IFFLCI_ENTRYHANDLER. 

When an ILBM BMHD is encountered, the entry handler is called, and it creates and stores another LCI having 
type equal to 'ILBM', ID equal to 'BMHD' and an identification value of IFFLCI_PROP. 

Thus, when you call FindProp(), it merely calls FindLocalltem() with your type and ID, and supplies 
IFFLCI_PROP for the identification value. 

Therefore, handlers, StoredProperties, Collectionltems and your own custom LCIs can never be confused with 
each other, since they all have unique identification values. Since they are all handled (and searched for) in the 
same way, they all "override" each other in a consistent way. Just as StoredProperties higher in the context 
stack will be found and returned before identical ones in lower contexts, so will chunk handlers be found and 
invoked before ones lower on the context stack (recall FindLocalltem()'s search procedure). 

This means you can temporarily override a chunk handler by installing an identical handler in a higher context. 
The handler will persist until the context in which it is stored expires, after which, the original one regains scope. 



Error Handling 



If at any time during reading or writing you encounter an error, the IFFHandle is left in an undefined state. Upon 
detection of an error, you should perform an abort sequence and CloselFFQ the IFFHandle. Once CloselFF() 
has been called, the IFFHandle is restored to normalcy and may be reused. 
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Advanced Topics 

This section discusses customizing of IFFParse data handling. For applications with special needs, IFFParse 
supports both custom stream handlers and custom chunk handlers. 



Custom Stream Handlers 

As discussed earlier, IFFParse contains built-in stream handlers for AmigaDOS file handles as returned by 
Open(), and for the clipboard. device. If you are using AmigaDOS filehandles or the clipboard.device, you need 
not supply a custom stream handler. 

If you wish to use your compiler's own file I/O functions (such as freadQ ) or need to read or write to an unusual 
handler or Exec device, you must provide a custom stream handler for your IFFHandle. Your custom stream 
handler will be called to perform all reads, writes, and seeks on your custom stream. The allows you to use 
compiler file I/O functions, Exec device commands, or any other method to perform the requested stream 
operations. 

If you are implementing your own custom stream handler, you will need to know the mechanics of hook 
call-backs, and how to interpret the parameters. An IFFParse custom stream handler is simply a function in your 
code that follows Release 2 hook function conventions (Hook functions are also known as callback functions. See 
the "Utility Library" chapter for more details). 

Installing a Custom Stream Handler 

To initialize your IFFHandle to point to your custom stream and stream handler, you must open your stream and 
place a pointer to the stream in your IFFHandle's iff_Stream field. This pointer could be the return from fopen(), 
or an Exec device I/O request, or any other type of pointer which will provide your custom stream handler with a 
way to manage your stream. For example: 

if f->iff_Stream = (ULONG) f open ( "f oo" ) ; 

Next, you must install your custom handler for this stream, and also tell IFFParse the seek capabilities of your 
stream. To install your custom stream handler, you must first set up a Hook structure (<utility/hooks.h>) to point 
to your stream handling function. Then use lnitlFF() to install your stream handler and also tell IFFParse the seek 
capabilities of your stream. There is "some assembly required". 

Release 2 hook function calling conventions specify a register interface. For an IFFParse custom stream hook, at 
entry, AO contains a pointer to the hook, A2 is a pointer to your IFFHandle, and A1 is a pointer to a command 
packet, which tells you what to do. A6 contains a pointer to IFFParseBase. You may trash AO, A1 , DO, and D1 . 
All other registers must be preserved. You return your error code in DO. A return of indicates success. A 
non-zero return indicates an error. 
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If your compiler supports registered function parameters, you may use a registerized C function entry as the 
h_Entry hook entry point: 

/* mystreamhandler - SAS C custom stream handler with */ 
/* registerized arguments */ 

static LONG saveds asm 

mystreamhandler ( 

register aO struct Hook *hook, 

register a2 struct IFFHandle *iff, 

register al struct IFFStreamCmd *actionpkt 

) 

{ 

/* * Code to handle the stream commands - see end this section 
* for a complete example custom stream handler function. 

*/ 
} 

/* Initialization of Hook structure for registerized */ 
/* handler function */ 

struct Hook mystreamhook { 

{ NULL } , 

(ULONG (*) ()) mystreamhandler, /* h_Entry, registerized function entry */ 

NULL, 

NULL 

}; 

/* Open custom stream and InitlFF to custom stream handler */ 



if ( if f->if f_Stream 
{ 



(ULONG) myopenC'foo") ) 



InitlFF (iff, IFFF_FSEEK | IFFF_RSEEK, Smystreamhook) ; 
} 



Alternately, you could initialize your Hook structure's h_Entry to point to a standard assembler stub which would 
push the register arguments on the stack and then call a standard args C function. In this case, you must store 
the address of your C function in the h_SubEntry field of the Hook structure so the assembler stub can find and 
call your C entry point. A sample assembler hook entry stub follows. This would be assembled as hookentry.o 
and linked with your C code. 

* HookEntry.asm for SAS C 

INCLUDE "exec/types. i" 
INCLUDE "utility/hooks. i" 

XDEF _HookEntry 

section code 



_HookEntry : 

move .1 a6 , - (sp) 

move .1 al , - (sp) 

move .1 a2 , - ( sp ) 

move .1 aO , - (sp) 

move . 1 h_SubEntry (aO ) , aO 

jsr (aO) 

lea 12 (sp) , sp 

move .1 (sp) +, a6 

rts 



push message packet pointer 
push object pointer 
push hook pointer 
fetch C entry point . . . 
. . . and call it 
fix stack 



end 
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When using an assembler HookEntry stub, your C program's custom stream handler interface would be 
initialized as follows: 



extern LONG HookEntry! 



/* The assembler entry */ 



/* mystreamhandler - a standard args C function custom stream handler*/ 

static LONG mystreamhandler ( struct Hook *hook, 

struct IFFHandle *iff, 

struct IFFStreamCmd *actionpkt ) 

{ 

/* Code to handle the stream commands - see end of this section 

* for a complete example custom stream handler function. 

*/ 
} 

/* Initialization of Hook for asm HookEntry and std args C function */ 
struct Hook mystreamhook { 

{ NULL } , 

(ULONG (*) ()) HookEntry, /* h_Entry, assembler stub entry */ 

(ULONG (*) ()) mystreamhandler, /* h_SubEntry, std args function entry */ 

NULL 



/* Open custom stream and InitlFF to custom stream handler */ 
if ( if f->iff_Stream = (ULONG) myopenC'foo") ) 



InitlFF (iff, IFFF_FSEEK | IFFF_RSEEK, kmystreamhook) ; 
} 



Inside a Custom Stream Handler 

When the library calls your stream handler, you'll be passed a pointer to the Hook structure (hook in the example 
used here), a pointer to the IFFHandle (iff), and a pointer to an IFFStreamCmd structure (actionpkt). Your 
stream pointer may be found in iff->iff_Stream where you previously stored it. The IFFStreamCmd (actionpkt) 
will describe the action that IFFParse needs you to perform on your stream: 

/* Custom stream handler is passed struct IFFStreamCmd *actionpkt */ 

struct IFFStreamCmd { 

LONG sc_Command; /* Operation to be performed (IFFCMD_) */ 
APTR sc_Buf; /* Pointer to data buffer */ 

LONG sc_NBytes; /* Number of bytes to be affected */ 

} ; 

/* Possible call-back command values. (Using as the value for 
* IFFCMD_INIT was, in retrospect, probably a bad idea.) 
*/ 

#define IFFCMD_INIT /* Prepare the stream for a session */ 

#define IFFCMD_CLEANUP 1 /* Terminate stream session */ 

#define IFFCMD_READ 2 /* Read bytes from stream */ 

#define IFFCMD_WRITE 3 /* Write bytes to stream */ 

ftdefine IFFCMD_SEEK 4 /* Seek on stream */ 

#define IFFCMD_ENTRY 5 /* You just entered a new context */ 

#define IFFCMD_EXIT 6 /* You're about to leave a context */ 

#define IFFCMD_PURGELCI 7 /* Purge a LocalContextltem */ 

Your custom stream handler should perform the requested action on your custom stream, and then return for 
success or an IFFParse error if an error occurred. The following code demonstrates a sample stream handler for 
a stream which was opened with a compiler's fopen() buffered file I/O function: 

static LONG mystreamhandler ( struct Hook *hook, 

struct IFFHandle *iff, 

struct IFFStreamCmd *actionpkt ) 

{ 

register FILE *stream; 

register LONG nbytes, error; 

register UBYTE *buf; 
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stream = (FILE *) if f ->if f_Stream; /* get stream pointer */ 
nbytes = actionpkt->sc_NBytes ; /* length for command */ 
buf = (UBYTE *) actionpkt->sc_Buf ; /* buffer for the command */ 

/* Now perform the action specified by the actionpkt->sc_Command */ 

switch (actionpkt->sc_Command) { 
case IFFCMD_READ: 

/* 

* IFFCMD_READ means read sc_NBytes from the stream and place 

* it in the memory pointed to by sc_Buf . Be aware that 

* sc_NBytes may be larger than can be contained in an int. 

* This is important if you plan on recompiling this for 

* 16-bit ints, since freadO takes int arguments. 

* Any error code returned will be remapped by IFFParse into 

* IFFERR_READ. 

*/ 

error = (fread (buf, 1, nbytes, stream) != nbytes) ; 
break; 

case IFFCMD_WRITE: 

/* 

* IFFCMD_WRITE is analogous to IFFCMD_READ. 
* 

* Any error code returned will be remapped by IFFParse into 

* IFFERR_WRITE. 

*/ 

error = (f write (buf, 1, nbytes, stream) != nbytes) ; 



} 



break; 

case IFFCMD_SEEK: 

/* 

* IFFCMD_SEEK asks that you performs a seek relative to the 

* current position. sc_NBytes is a signed number, 

* indicating seek direction (positive for forward, negative 

* for backward) . sc_Buf has no meaning here. 

* Any error code returned will be remapped by IFFParse into 

* IFFERR_SEEK. 

*/ 

error = (fseek (stream, nbytes, 1) == -1) ; 
break; 

case IFFCMD_INIT: 

/* 

* IFFCMD_INIT means to prepare your stream for reading. 

* This is used for certain streams that can't be read 

* immediately upon opening, and need further preparation. 

* This operation is allowed to fail; the error code placed 

* in DO will be returned directly to the client. 
* 

* An example of such a stream is the clipboard. The 

* clipboard. device requires you to set the io_ClipID and 

* io_Offset to zero before starting a read. You would 

* perform such a sequence here. (Stdio files need no such 

* preparation, so we simply return zero for success.) 

*/ 

case IFFCMD_CLEANUP: 

/* 

* IFFCMD_CLEANUP means to terminate the transaction with 

* the associated stream. This is used for streams that 

* can't simply be closed. This operation is not allowed to 

* fail; any error returned will be ignored. 
* 

* An example of such a stream is (surprise!) the clipboard. 

* It requires you to explicitly end reads by CMD_READing 

* past the end of a clip, and end writes by sending a 

* CMD_UPDATE . You would perform such a sequence here . 

* (Again, stdio needs no such sequence.) 

*/ 

error = ; 
break; 

} 

return (error) ; 
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Custom Chunk Handlers 

Like custom stream handlers, custom chunk handlers are implemented using Release 2 Hook structures. See 
the previous section for details on how a handler function may be interfaced using a Hook structure. 

There are two types of chunk handlers: entry handlers and exit handlers. Entry handlers are invoked just after the 
parser enters the chunk; the stream will be positioned to read the first byte in the chunk. (If the chunk is a FORM, 
LIST, CAT, or PROP, the longword type will be read by the parser; the stream will be positioned to read the byte 
immediately following the type.) Exit handlers are invoked just before the parser leaves the chunk; the stream is 
not positioned predictably within the chunk. 

Installing a Custom Chunk Handler 

To install an entry handler, you call EntryHandler() in the following manner: 

error = EntryHandler (iff, type, id, position, hookptr, object); 
An exit handler is installed by saying: 



error = ExitHandler (iff, type, id, position, hookptr, object); 

In both cases, a handler is installed for chunks having the specified type and id. The position argument specifies 
in what context to install the handler, and is identical to the position argument used by Storel_ocalltem(). The 
hookptr argument given above is a pointer to your Hook structure. 

Inside a Custom Chunk Handler 

The mechanics of receiving parameters through the Hook are covered in the "Custom Stream Handlers" section, 
and are not duplicated here. Refer to the EntryHandlerQ and ExitHandlerQ Autodocs for the contents of the 
registers upon entry. 

Once inside your handler, you can call nearly all functions in the iffparse. library, however, you should avoid calling 
ParselFF() from within chunk handlers. 

Your handler runs in the same environment as whoever called ParselFFQ. The propagation sequence is: 



mainline |--calls-->| ParselFFO |--calls-->| your_handler ( 



Thus, your handler runs on your mainline's stack, and can call any OS functions the mainline code can. (Your 
handler will have to set the global base pointer if your code uses base-relative addressing.) 

When leaving the handler, you must follow the standard register preservation conventions (D0/D1/A0/A1 may be 
trashed, all others must be preserved). DO contains your return code, which will affect the parser in a number of 
ways: 

If you return zero (a normal, uneventful return), ParselFF() will continue normally. If you return the value 
IFFERR_RETURN2CLIENT, ParselFF() will stop and return the value zero to the mainline code. 

If you return any other value, ParselFF() will stop and return that value to the mainline code. This is how you 
should return error conditions to the client code. 

IFFParse Library 797 

The Object Parameter 

The object parameter supplied to EntryHandler() and ExitHandlerQ is a pointer which will be passed to your 
handler when invoked. This pointer can be anything; the parser doesn't use it directly. As an example, you might 
pass the pointer to the IFFHandle. This way, when your handler is called, you'll be able to easily perform 
operations on the IFFHandle within your handler. Such code might appear as follows: 

error = EntryHandler (iff, ID_ILBM, ID_BMHD, IFFSLI_ROOT, hook, iff) ; 

And your handler would be declared as follows: 

/* Registerized handler hook h_Entry using */ 
/* SAS C registerized parameters */ 

LONG asm MyHandler (register aO struct Hook *hook, 

register al LONG *cmd, 

register a2 struct IFFHandle *iff) 

/* Standard args handler hook h_SubEntry using */ 
/* HookEntry .asm as Hook h_Entry */ 

LONG MyHandler ( struct Hook *hook, 

LONG * cmd , 

struct IFFHandle *iff ) 

From within your handler, you could then call CurrentChunk(), ReadChunkBytes(), or nearly any other operation 
on the IFFHandle. Please refer to the EntryHandlerQ and ExitHandler() Autodocs for additional information on 
the use of chunk handlers. 



Finding the Prop Context 

Earlier it was mentioned that supplying a position value of IFFSLI_PROP to StoreLocalltem() would store it in the 
topmost property scope. FindPropContext() is the routine that finds that topmost context. 

Property chunks (such as the BMHD, CMAP, and others) have dominion over the FORM that contains them; they 
are said to be "in scope" and their definition persists until the FORM'S context ends. Thus, a property chunk has a 
scoping level equal to the FORM that contains it; when the FORM ends, the property dies with it. 

Consider a more complicated example. Suppose you have a LIST with a PROP in it. PROPs are the global 
variables of LISTs; thus a property chunk declared in a PROP will persist until the LIST'S context ends. 

This is what FindPropContext() is looking for; a context level in which a property chunk may be installed. 

FindPropContext() starts at the parent of the current context (second from the top of the context stack) and starts 
searching downward, looking for the first FORM or LIST context it finds. If it finds one, it returns a pointer to that 
ContextNode. If it can't find a suitable context level, it returns NULL. 

FindPropContext() is called as follows: 

struct ContextNode *cn; 

en = FindPropContext (iff) ; 
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Freeing LCIs 

Ordinarily, the parser will automatically delete LCIs you have allocated and installed. However, you may have a 
case where simply FreeMem()ing your LCI is not enough; you may need to free some ancillary memory, or 
decrement a counter, or send a signal, or something. This is where SetLocalltemPurge() comes in. It is called 
as follows: 

SetLocalltemPurge (lei, hookptr) ; 

When the parser is ready to delete your LCI, your purge handler code will be called through the Hook you 
supplied. You can then perform all your necessary operations. One of these operations should be to free the LCI 
itself. This is done with FreeLocalltem(): 

FreeLocalltem (lei) ; 

This deallocates the memory used to store the LCI and the client buffer allocated with it. FreeLocalltem() is only 
called as part of a custom purge handler. 

As with custom chunk handlers, your purge handler executes in the same environment as the mainline code that 
called ParselFFQ. It is recommended that you keep purge handlers short and to the point; super clever stuff 
should be reserved for custom chunk handlers, or for the client's mainline code. Custom purge handlers must 
always work; failures will be ignored. 



IFF FORM Specifications 



The specifications for Amiga IFF formats are maintained by Commodore Applications and Technical Support 
(CATS) and updated periodically. The latest specifications are published in the Amiga ROM Kernel Reference 
Manual: Devices (3rd edition) and also available in electronic form directly from CATS. Between updates of the 
IFF Manual, selected new FORMs and changes to existing FORMs are documented in Amiga Mail a technical 
newsletter for Amiga developers published by Commodore's CATS group. 

Some of the most commonly used IFF FORMs are the four that were originally specified in the EA IFF-85 
standard: 



ILBM Bitmap images and palettes 

FTXT Simple formatted text 

SMUS Simple musical scores 

8SVX 8 -bit sound samples 



Of these four, ILBM is the most commonly encountered FORM, and FTXT is becoming increasingly important 
since the Release 2 conclip command passes clipped console text through the clipboard as FTXT. All data 
clipped to the clipboard must be in an IFF format. 

This section will provide a brief summary of the ILBM and FTXT FORMs and their most used common chunks. 
Please consult the EA-IFF specifications for additional information. 
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FORM ILBM 



The IFF file format for graphic images on the Amiga is called FORM ILBM (InterLeaved BitMap). It follows a 
standard parsable IFF format. 

ILBM.BMHD BitMapHeader Chunk 

The most important chunk in a FORM ILBM is the BMHD (BitMapHeader) chunk which describes the size and 
compression of the image: 



typedef UBYTE Masking; /* Choice of masking technique 
#define mskNone 

#define mskHasMask 1 

#define mskHasTransparentColor 2 
#define mskLasso 3 



Usually 0. */ 



/* Compression algorithm applied to the rows of all source 

* and mask planes. "cmpByteRunl" is byte run encoding. 

* Do not compress across rows! Compression is usually 1. 

*/ 

typedef UBYTE Compression; 
#define cmpNone 

#define cmpByteRunl 1 

/* The BitMapHeader structure expressed as a C structure */ 
typedef struct { 

UWORD w, h; I* 

WORD x, y; /* 

UBYTE nPlanes; /* 

Masking masking; /* 

Compression compression; /* 

UBYTE reserved!; /* 

UWORD transparentColor; /* 

UBYTE xAspect, yAspect ; /* 

WORD pageWidth, pageHeight; 
} BitMapHeader; 



raster width & height in pixels */ 
pixel position for this image */ 
# bitplanes (without mask, if any) */ 
One of the values above. Usually */ 
One of the values above. Usually 1 */ 
reserved; ignore on read, write as */ 
transparent color number. Usually */ 
pixel aspect, a ratio width : height */ 
/* source "page" size in pixels */ 



Sample Hex Dump of an ILBM 

WARNING:Jh\s hex dump is shown only to help the reader understand how IFF chunks 
appear in a file. You cannot ever depend on any particular ILBM chunk being at any particular 
offset into the file. IFF files are composed, in their simplest form, of chunks within a FORM. 
Each chunk starts with a 4-letter chunkID, followed by a 32-bit length of the rest of the chunk. 
You must parse IFF files, skipping past unneeded or unknown chunks by seeking their length 
(+1 if odd length) to the next 4-letter chunk ID. In a real ILBM file, you are likely to encounter 
additional optional chunks. See the IFF Specification listed in the Amiga ROM Kernel 
Reference Manual: Devices for additional information on such chunks. 



0000: 464F524D 00016418 494C424D 424D4844 
0010: 00000014 01400190 00000000 06000100 
0020: 00000A0B 01400190 43414D47 00000004 



FORM. .d.ILBMBMHD 



0030 
0040 
0050 
0060 
0070 
etc 



00000804 434D4150 00000030 001000E0 . . . . CMAP . . . . . . . 

E0E00000 20000050 30303050 50500030 POOOPPP.O 

90805040 70707010 60E02060 E06080D0 . . POppp . ' . ' .'.. 

A0A0A0A0 90E0C0C0 C0D0A0E0 424F4459 BODY 

000163AC F8000F80 148A5544 2ABDEFFF . .c UD* . . . 



Interpretation : 

'FORM' length 'I L B M"B M H D' <- start of BitMapHeader chunk 
0000: 464F524D 00016418 494C424D 424D4844 FORM . . d . ILBMBMHD 

Planes Mask length WideHigh XorgYorg PIMkCoRe <- Compression Reserved 
0010: 00000014 01400190 00000000 06000100 @ 
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TranAspt PagwPagh 'C A M G' length <- start of C-AMIGa View modes chunk 
0020: 00000A0B 01400190 43414D47 00000004 @ . . CAMG . . . . 

dir include: 

ViewMode 'CMAP' length R g b R <- ViewMode 800=HAM | 4=LACE 
0030: 00000804 434D4150 00000030 001000E0 . . . . CMAP . . . . . . . 

gbRg bRgb RgbR gbRg<- Rgb's are for regO thru regN 
0040: E0E00000 20000050 30303050 50500030 POOOPPP.O 

bRgb RgbR gbRg bRgb 
0050: 90805040 70707010 60E02060 E06080D0 . . POppp . ' . '.'.. 

RgbR gbRg bRgb 'BODY' 
0060: A0A0A0A0 90E0C0C0 C0D0A000 424F4459 BODY 

length start of body data <- Compacted (Compression^ above) 

0070: 000163AC F8000F80 148A5544 2ABDEFFF ..c UD* . . . 

0080: FFBFF800 0F7FF7FC FF04F85A 77AD5DFE Zw . ] . etc. 

Simple CAMG ViewMode s : HIRES=0x8000 LACE=0x4 HAM=0x800 HALFBRITE=0x80 

( Release 2 ILBMs may contain a LONGWORD Viewport ModelD in CAMG ) 

Interpreting ILBMs 

ILBM is a fairly simple IFF FORM. All you really need to deal with to extract the image are the following chunks: 

BMHD 

Information about the size, depth, compaction method (see interpreted hex dump above). 

CAMG 

Optional Amiga ViewModes chunk. Most HAM and HALFBRITE ILBMs should have this chunk. If no 
CAMG chunk is present, and image is 6 planes deep, assume HAM and you'll probably be right. Some 
Amiga ViewModes flags are HIRES=0x8000, LACE=0x4, HAM=0x800, HALFBRITE=0x80. 2.0 ILBM 
writers should write a full 32-bit mode ID in the CAMG. See the IFF Manual for more information on 
writing and interpreting 32-bit CAMG values. 

CMAP 

RGB values for color registers to N. Previously, 4-bit RGB components each left justified in a byte. 
These should now be stored as a full 8-bit RGB values by duplicating 4-bit values in the high and low 
nibble of the byte. 

BODY 

The pixel data, stored in an interleaved fashion as follows (each line individually compacted if BMHD 
Compression = 1): 

plane scan line 

plane 1 scan line 

plane 2 scan line 

plane n scan line 

plane scan line 1 



plane 1 scan line 1 
etc. 

Optional Chunks 

Also watch for AUTH Author chunks and (c) copyright chunks and preserve any copyright information if 
you rewrite the ILBM. 
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ILBM BODY Compression 

The BODY contains pixel data for the image. Width, Height, and depth (Planes) is specified in the BMHD. 

If the BMHD Compression byte is 0, then the scan line data is not compressed. If Compression^ , then each scan 
line is individually compressed as follows: 

while (not produced the desired number of bytes) 
/* get a byte, call it N */ 

if (N >= && N <= 127) /* copy the next N+l bytes literally */ 

if (N >= -127 && N <= -1) /* repeat the next byte N+l times */ 

if (N == -128) /* skip it, presumably it's padding */ 

Interpreting the Scan Line Data 

If the ILBM is not HAM or HALFBRITE, then after parsing and uncompacting if necessary, you will have N planes 
of pixel data. Color register used for each pixel is specified by looking at each pixel thru the planes. For instance, 
if you have 5 planes, and the bit for a particular pixel is set in planes and 3: 

PLANE 4 3 2 10 
PIXEL 10 1 

then that pixel uses color register binary 01001 = 9. 

The RGB value for each color register is stored in the CMAP chunk of the ILBM, starting with register 0, with each 
register's RGB value stored as one byte of R, one byte G, and one byte of B, with each component left justified in 
the byte. (ie. Amiga R, G, and B components are each stored in the high nibble of a byte) 

But, if the picture is HAM or HALFBRITE, it is interpreted differently. Hopefully, if the picture is HAM or 
HALFBRITE, the package that saved it properly saved a CAMG chunk (look at a hex dump of your file with ASCII 
interpretation - you will see the chunks - they all start with a 4-ASCII-char chunk ID). If the picture is 6 planes 
deep and has no CAMG chunk, it is probably HAM. If you see a CAMG chunk, the 'CAMG' is followed by the 
32-bit chunk length, and then the 32-bit Amiga view mode flags. 

HAM pictures will have the 0x800 bit set in CAMG chunk ViewModes. HALBRITE pictures will have the 0x80 bit 
set. See the graphics library chapters or the Amiga Hardware Reference Manual for more information on HAM 
and HALFBRITE modes. 

Other ILBM Notes 

Amiga ILBMs images must be stored as an even number of bytes in width. However, the ILBM BMHD field w 
(width) should describe the actual image width, not the rounded up width as stored. 

ILBMs created with Electronic Arts IBM or Amiga Deluxe Paint //packages are compatible (though you may have 
to use a '.Ibm' filename extension on an IBM). The ILBM graphic files may be transferred between the machines 
(or between the Amiga and IBM sides your Amiga if you have a CBM Bridgeboard card installed) and loaded into 
either package. 
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FORM FTXT 

The FTXT (Formatted TeXT) form is the standard format for sharing text on the Amiga. The Release 2 console 
device clip and paste functions, in conjunction with the startup-sequence conclip command, pass clipped console 
text through the clipboard as FTXT. 



By supporting reading and writing of clipboard device FTXT, your application will allow users to cut and paste text 
between your application, other applications, and Amiga Shell windows. 

The FTXT form is very simple. Generally, for clip and paste operations, you will only be concerned with the 
CHRS (character string) chunks of an FTXT. There may be one or more CHRS chunks, each of which contains a 
non-NULL-terminated string of ASCII characters whose length is equal to the length (Stored Property.sp_Size) of 
the chunk. 

Be aware that if you CollectionChunk() the CHRS chunks of an FTXT, the list accumulated by IFFParse will be 
in reverse order from the chunk order in the file. See the ClipFTXT.c example at the end of this chapter for a 
simple example of reading (and optionally writing) FTXT to and from the clipboard. See also the "Clipboard 
Device" and "Console Device" chapters of the Amiga ROM Kernel Reference Manual: Devices for more 
information on Release 2 console clip and paste. 



IFFParse Examples 



Two examples follow: ClipFTXT.c, and Sift.c. These are simple examples that demonstrate the use of the 
IFFParse library. More complex examples for displaying and saving ILBMs may be found in the IFF Appendix of 
the Amiga ROM Kernel Reference Manual: Devices. 

Clipboard FTXT Example 

ClipFTXT.c demonstrates reading (and optinal writing) of clipboard device FTXT. This example may be used as 
the basis for supporting Release 2 console pastes. 

;/* clipftxt.c - Execute me to compile me with SAS C 5.10 

LC -bl -cfistq -v - j 73 clipftxt.c 

Blink FROM LIB : c . o, clipf txt . o TO clipftxt LIBRARY LIB : LC . lib, LIB : Amiga . lib 

quit 

* ClipFTXT.c demonstrates reading (and optional writing) of clipboard 

* device FTXT. This example may be used as the basis for supporting 

* Release 2 console pastes. 

* clipftxt.c: Writes ASCII text to clipboard unit as FTXT 

* (All clipboard data must be IFF) 

* Usage: clipftxt unitnumber 

* To convert to an example of reading only, comment out #define WRITEREAD 
*/ 

#include <exec/types .h> 
#include <exec/memory . h> 
#include <libraries/dos . h> 
#include <libraries/if fparse . h> 

#include <clib/exec_protos . h> 
#include <clib/dos_protos .h> 
#include <clib/if fparse_protos . h> 
#include <stdlib.h> 
#include <stdio.h> 
#include <string.h> 

#ifdef LATTICE 

int CXBRK(void) { return(O); } /* Disable Lattice CTRL/C handling */ 

int chkabort (void) { return(O); } /* really */ 

#endif 

/* Causes example to write FTXT first, then read it back 
* Comment out to create a reader only 

*/ 

#define WRITEREAD 

#define MINARGS 2 

/* 2.0 Version string for c: Version to find */ 
UBYTE vers [] = "\0$VER: clipftxt 37.2"; 



UBYTE usage [] = "Usage: clipftxt unitnumber (use zero for primary unit)"; 

/* 

* Text error messages for possible IFFERR_#? returns from various 

* IFF routines. To get the index into this array, take your IFFERR code, 

* negate it, and subtract one. 

* idx = -error - 1; 

*/ 

char *errormsgs [] = { 

"End of file (not an error) .", 

"End of context (not an error) .", 

"No lexical scope.", 

"Insufficient memory.", 

"Stream read error.", 

"Stream write error.", 

"Stream seek error.", 

"File is corrupt.", 

"IFF syntax error.", 

"Not an IFF file. " , 

"Required call-back hook missing.", 

"Return to client. You should never see this." 

}; 

#define RBUFSZ 512 

#define ID_FTXT MAKE_ID ( ' F' , ' T' , ' X' , ' T' ) 
#define ID_CHRS MAKE_ID ( ' C , 'H' , ' R' , ' S' ) 

struct Library *IFFParseBase; 

UBYTE mytext [] ="This FTXT written to clipboard by clipftxt example . \n" ; 

void main(int argc, char **argv) 

{ 

struct IFFHandle *iff = NULL; 

struct ContextNode *cn; 

long error=0, unitnumber=0 , rlen; 

int textlen; 

UBYTE readbuf [RBUFSZ] ; 

/* if not enough args or '?', print usage */ 

if ( ( (argc) && (argc<MINARGS) ) | | (argv [argc-1] [0] =='?') ) 

{ 

printf ( " %s\n" , usage) ; 

exit (RETURN WARN) ; 



unitnumber = atoi (argv[l] ) ; 

if ( ! (IFFParseBase = OpenLibrary ( "if fparse . library" , 0L) ) ) 

{ 

puts("Can't open iff parsing library."); 

goto bye; 

} 

/* 

* Allocate IFF_File structure. 

*/ 

if ( ! (iff = AllocIFF () ) ) 

{ 

puts ( "AllocIFF () failed."); 

goto bye; 

} 

/* 

* Set up IFF_File for Clipboard I/O. 

*/ 

if ( ! (if f->if f_Stream = (ULONG) OpenClipboard (unitnumber))) 

{ 

puts ("Clipboard open failed."); 

goto bye; 

} 



else printf ( "Opened clipboard unit %ld\n" ,unitnumber) ; 
InitlFFasClip (iff) ; 
#ifdef WRITEREAD 

/* 

* Start the IFF transaction. 

*/ 

if (error = OpenlFF (iff, IFFF_WRITE) ) 

{ 

puts ("OpenlFF for write failed."); 

goto bye; 

} 

/* 

* Write our text to the clipboard as CHRS chunk in FORM FTXT 

* First, write the FORM ID (FTXT) 

*/ 

if ( ! (error=PushChunk(iff , ID_FTXT, ID_FORM, IFFSIZE_DNKNOWN) ) ) 

{ 

/* Now the CHRS chunk ID followed by the chunk data 

* We'll just write one CHRS chunk. 

* You could write more chunks. 

*/ 

if ( ! (error=PushChunk(if f , 0, ID_CHRS, IFFSIZE_UNKNOWN) ) ) 

{ 

/* Now the actual data (the text) */ 

textlen = strlen (mytext) ; 

if (WriteChunkBytes (if f , mytext, textlen) != textlen) 

{ 

puts("Error writing CHRS data."); 
error = IFFERR_WRITE; 
} 
} 
if(!error) error = PopChunk (if f ) ; 

} 
if(!error) error = PopChunk (if f) ; 

if (error) 

{ 

printf ("IFF write failed, error %ld: %s\n", 

error, errormsgs [-error - 1] ) ; 
goto bye; 

} 
else printf ( "Wrote text to clipboard as FTXT\n"); 

/* 

* Now let's close it, then read it back 

* First close the write handle, then close the clipboard 

*/ 

CloseIFF(iff ) ; 

if (if f ->if f_Stream) CloseClipboard ( (struct ClipboardHandle *) 

if f ->if f_Stream) ; 

if ( ! (if f ->if f_Stream = (ULONG) OpenClipboard (unitnumber) ) ) 

{ 

puts ("Reopen of Clipboard failed."); 

goto bye; 

} 
else printf ( "Reopened clipboard unit %ld\n" .unitnumber) ; 

#endif /* WRITEREAD */ 

if (error = OpenlFF (iff, IFFF_READ) ) 

{ 

puts ("OpenlFF for read failed."); 

goto bye; 

} 

/* Tell iffparse we want to stop on FTXT CHRS chunks */ 



bye : 



if (error = StopChunk (if f , ID_FTXT, ID_CHRS) ) 

{ 

puts ("StopChunk failed."); 

goto bye; 

} 

/* Find all of the FTXT CHRS chunks */ 
while (1) 

{ 

error = ParselFF (if f , IFFPARSE_SCAN) ; 

if (error == IFFERR_E0C) continue; /* enter next context */ 

else if (error) break; 

/* We only asked to stop at FTXT CHRS chunks 

* If no error we've hit a stop chunk 

* Read the CHRS chunk data 

*/ 

en = CurrentChunk (if f ) ; 

if ( (en) &&(cn->cn_Type == ID_FTXT) && (cn->cn_ID == ID_CHRS) ) 

{ 

printf("CHRS chunk contains : \n" ) ; 

while ( (rlen = ReadChunkBytes (if f , readbuf , RBUFSZ) ) > 0) 

{ 

Write (Output ( ) , readbuf , rlen) ; 

} 
if (rlen < 0) error = rlen; 

} 
} 

if ( (error) && (error != IFFERR_EOF) ) 

{ 

printf ("IFF read failed, error %ld: %s\n", 

error, errormsgs [-error - 1] ) ; 
} 

if (iff) { 
/* 

* Terminate the IFF transaction with the stream. Free 

* all associated structures. 

*/ 

CloselFF (iff) ; 

/* 

* Close the clipboard stream 

*/ 

if (if f->if f_Stream) 

CloseClipboard ((struct ClipboardHandle *) 
if f ->if f_Stream) ; 

/* 

* Free the IFF_File structure itself. 

*/ 

FreelFF (iff) ; 

} 
if (IFFParseBase) CloseLibrary (IFFParseBase) ; 

exit (RETURNJDK) ; 
} 
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IFF Scanner Example 

Sift.c lists the type and size of every chunk in an IFF file and, and checks the IFF file for correct syntax. You 
should use Sift to check IFF files created by your programs. 

;/* sift.c - Execute me to compile me with SAS C 5.10 

LC -bl -cfistq -v -J73 sift.c 

Blink FROM LIB : c . o, sift . o TO sift LIBRARY LIB : LC . lib, LIB : Amiga . lib 

quit 

* Sift.c lists the type and size of every chunk in an IFF file and 



* checks the IFF file for correct syntax. You should use Sift to 

* check IFF files created by your programs. 
* 

* sif t . c : Takes any IFF file and tells you what's in it. Verifies syntax and all that cool stuff. 
* 

* Usage : sift -c ; For clipboard scanning 

* or sift <file> ; For DOS file scanning 
* 

* Reads the specified stream and prints an IFFCheck-like listing of the contents of the IFF file, if any. 

* Stream is a DOS file for <f ile> argument , or is the clipboard' s primary clip for -c . 

* This program must be run from a CLI . 
* 

*/ 

#include <exec/types . h> 
#include <exec/memory . h> 
#include <libraries/dos . h> 
#include <libraries/if fparse . h> 
#include <clib/exec_protos . h> 
#include <clib/dos_protos . h> 
#include <clib/if f parse_protos . h> 
#include <stdlib.h> 
#include <stdio.h> 
#include <string.h> 

#ifdef LATTICE 

int CXBRK(void) { return(O); } /* Disable Lattice CTRL/C handling */ 

int chkabort (void) { return(O); } /* really */ 

#endif 

#define MINARGS 2 

UBYTE vers [] = "\0$VER: sift 37.1"; /* 2.0 Version string for c:Version to find */ 
UBYTE usage [] = "Usage: sift IFFfilename (or -c for clipboard)"; 

void PrintTopChunk (struct IFFHandle *) ; /* proto for our function */ 

/* 

* Text error messages for possible IFFERR_#? returns from various IFF routines. To get the index into 

* this array, take your IFFERR code, negate it, and subtract one. 

* idx = -error - 1; 

*/ 

char *errormsgs [] = { 

"End of file (not an error) .", "End of context (not an error) .", "No lexical scope." 
"Insufficient memory.", "Stream read error.", "Stream write error.", 
"Stream seek error.", "File is corrupt.", "IFF syntax error.", 
"Not an IFF file.", "Required call-back hook missing.", 
"Return to client. You should never see this." 

}; 

struct Library *IFFParseBase; 

void main (int argc, char **argv) 

{ 

struct IFFHandle *iff = NULL; 

long error; 

short cbio; 

/* if not enough args or '?', print usage */ 

if ( ( (argc) && (argc<MINARGS) ) | | (argv [argc-1] [0] =='?') ) 

{ 

print f ( "%s\n" , usage) ; 

goto bye; 

} 

/* Check to see if we are doing I/O to the Clipboard. */ 
cbio = (argv[l] [0] == '-' && argv[l] [1] == 'c'); 

if ( ! (IFFParseBase = OpenLibrary ( "if fparse . library" , 0L) ) ) 

{ 

puts("Can't open iff parsing library."); 

goto bye; 

} 



/* Allocate IFF_File structure. */ 
if ( ! (iff = AllocIFF () ) ) 

{ 

puts ( "AllocIFF () failed."); 
goto bye; 
} 
/* 

* Internal support is provided for both AmigaDOS files , and the clipboard. device . This bizarre 
* 'if statement performs the appropriate machinations for each case . 

*/ 

if (cbio) 

{ 
/* 

* Set up IFF_File for Clipboard I/O. 

*/ 

if ( ! (if f->if f_Stream = 

(ULONG) OpenClipboard (PRIMARY_CLIP) ) ) 

{ 

puts ("Clipboard open failed."); 

goto bye; 

} 
InitlFFasClip (iff) ; 

} 
else 

{ 

/* Set up IFF_File for AmigaDOS I/O. */ 

if ( ! (if f->iff_Stream = Open (argv[l], MODEJDLDFILE) ) ) 

{ 

puts ("File open failed."); 

goto bye; 

} 
InitlFFasDOS (iff) ; 

} 

/* Start the IFF transaction. */ 

if (error = OpenlFF (iff, IFFF_READ) ) 

{ 

puts ("OpenlFF failed."); 

goto bye; 

} 

while (1) 
{ 
/* 

* The interesting bit. IFFPARSE_RAWSTEP permits us to have precision monitoring of the 

* parsing process, which is necessary if we wish to print the structure of an IFF file. 

* ParseIFF() with _RAWSTEP will return the following things for the following reasons: 
* 

* Return code: Reason: 

* Entered new context . 

* IFFERR_EOC About to leave a context. 

* IFFERR_EOF Encountered end-of-file. 

* <anything else> A parsing error. 

*/ 

error = ParselFF (iff, IFFPARSE_RAWSTEP) ; 

/* 

* Since we're only interested in when we enter a context, we "discard" end-of -context 

* (_EOC) events. 

*/ 

if (error == IFFERR_EOC) 

continue; 
else if (error) 

/* 

* Leave the loop if there is any other error. 

*/ 

break; 



/* If we get here, error was zero. Print out the current state of affairs. */ 

PrintTopChunk (iff) ; 

} 



bye : 



/* 

* If error was IFFERR_EOF, then the parser encountered the end of 

* the file without problems. Otherwise, we print a diagnostic. 

*/ 

if (error == IFFERR_EOF) 

puts ("File scan complete."); 
else 

printf ("File scan aborted, error %ld: %s\n", 
error, errormsgs [-error - 1] ) ; 

if (iff) { 

/* Terminate the IFF transaction with the stream. Free all associated structures. */ 
CloselFF (iff) ; 

/* 

* Close the stream itself. 

*/ 

if (if f->if f_Stream) 
if (cbio) 

CloseClipboard ((struct ClipboardHandle *) 
if f ->if f_Stream) ; 
else 

Close (if f->if f_Stream) ; 

/* Free the IFF_File structure itself. */ 
FreelFF (iff) ; 



if (IFFParseBase) 


CloseLit 


exit (RETURN OK) ; 
} 




void 

PrintTopChunk (iff) 

struct IFFHandle *iff; 

{ 

struct ContextNode 

short 

char 




*top; 
i ; 
idbuf [5] 



} 



/* Get a pointer to the context node describing the current context. */ 
if (!(top = CurrentChunk (iff))) 
return; 

/* 

* Print a series of dots equivalent to the current nesting depth of chunks processed so far. 

* This will cause nested chunks to be printed out indented. 

*/ 

for (i = if f ->if f_Depth; i--; ) 
printf ( " . " ) ; 

/* Print out the current chunk's ID and size. */ 

printf ("%s %ld ", IDtoStr (top->cn_ID, idbuf), top->cn_Size) ; 

/* Print the current chunk's type, with a newline. */ 
puts (IDtoStr (top->cn_Type, idbuf) ) ; 
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Function Reference 

The following are brief descriptions of the IFFParse functions discussed in this chapter. IFFParse library functions 
are avialable in Release 2 of the Amiga OS and are backward compatible with older versions of the system. 
Further information about these and other IFFParse functions can be found in the 3rd edition of the Amiga ROM 
Kernel Reference Manual: Includes and Autodocs, also from Addison-Wesley. 



Table 33-2: IFFParse Library Functions 



Function 



A II OC lFF () 
FreelFF() 
OpenlFF() 
CloselFFQ 



Description 

Creates an IFFHandle structure. 

Frees the IFFHandle structure created with AlloclFF(). 

Initialize an IFFHandle structure to read or write an IFF stream. 

Closes an IFF context. 



Initll-K) 

InitlFFasDOSO 
InitlFFasClipQ 



initialize an ihhMandie as a user-cfetined stream. 
Initialize an IFFHandle as an AmigaDOS stream. 
Initialize an IFFHandle as a clipboard stream. 



OpenChpboard() 

ParselFF() 

ReadChunkBytes() 

ReadChunkRecords() 

StopChunk() 

CurrentChunk() 

PropChunk() 

FindProp() 

CollectionChunk() 

FindCollection() 

StopOnExit() 

EntryHandler() 

ExitHandlerQ 



Create a handle on a clipboard unit tor lmtll-l-asClip(). 

Parse an IFF file from an IFFHandle stream. 

Read bytes from current chunk into a buffer. 

Read record elements from the current chunkinto a buffer. 

Declare a chunk that should cause ParselFF() to return. 

Get the context node for the current chunk. 

Specify a property chunk to store. 

Search for a stored property in a given context. 

Declare a chunk type for collection. 

Get a pointer to the current list of collection items. 

Declare a stop condition for exiting a chunk. 

Add an entry handler to the IFFHandle context. 

Add an exit handler to the IFFHandle context. 



PushChunk() Push a given context node onto the top of the context stack. 

PopChunk() Pop the top context node off of the context stack. 

CurrentChunk() Get the top context node for the current chunk. 

ParentChunkQ Get the nesting context node for a given chunk. 



AllocLocalltemO 

Local Item Data() 

StoreLocalltem() 

StoreltemlnContext() 

FindPropContext() 

FindLocalltem() 

FreeLocalltem() 

SetLocalltemPurgeQ 



Create a LocalContextltem (LCI) structure. 

Returns a pointer to the user data of a LocalContextltem (LCI). 

Insert a LocalContextltem (LCI). 

Store a LocalContextltem in a given context node. 

Find the property context for the current state. 

Return a LocalContextltem from the context stack. 

Free a LocalContextltem (LCI) created with AllocLocalltem(). 

Set purge vector for a local context item. 
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Chapter 34 
Keymap Library 



Amiga computers are sold internationally with a variety of local keyboards which match the standards of particular 
countries. All Amigas have keyboards which are physically similar, and keys which output the same low-level raw 
key code for any particular physical key. However, in different countries, the keycaps of the keys may contain 
different letters or symbols. Since the physical position of a key determines the raw key code that it generates, 
raw key codes are not internationally compatible. For instance, on the German keyboard, the Y and Z keys are 
swapped when compared to the USA keyboard. The second key on the fifth row will generate the same raw key 
code on all Amiga keyboards, but should be decoded as a Z on a US keyboard and as a Y on a German 
keyboard. 

The Amiga uses the ECMA-94 Latinl International 8-bit character set, and can map raw key codes to any desired 
ANSI character value, string, or escape sequence. This allows national keyboards to be supported by using 
keymaps. A keymap is a file which describes what character or string is tied to what key code. Generally, the 
user's startup-sequence will set a system default keymap that is correct for the user's keyboard. The 
console. device translates the raw key codes into the correct characters based on the installed keymap. This 
includes the translation of special deadkey sequential key combinations to produce accented international 
characters. 

Programs which perform keyboard input using the console. device, CON:, RAW:, or Intuition VANILLAKEY, will 
receive the correct ASCII values for a user's keycaps, based on their keymap. But some applications may require 
custom keymaps, or may need to perform their own translation between raw key codes and ANSI characters. In 
this chapter, the term ANSI refers to standard 8-bit character definitions which include printable ASCII characters, 
special characters, and escape sequences. 

Until V37, keymapping commands were only available in the console. device. Keymap. library is a new library in 
Release 2 (V37). It offers the some of the keymap commands of the console. device, enabling applications to 
inquire after the default keymap and map key codes to ANSI characters. It also provides the ability to map ANSI 
characters back into raw codes. Unlike the console.device however, it can not be used to select a keymap for only 
one application, i.e., one console window. 

As a prelude to the following material, note that the Amiga keyboard transmits raw key information to the 
computer in the form of a key position and a transition. Raw key positions range from hexadecimal 00 to 7F. 
When a key is released, its raw key position, plus hexadecimal 80, is transmitted. 
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Keymap Functions 



Table 34-1 : Keymap Library Functions 



AskKeyMapDef ault i 
MapANSI () 



Ask for a pointer to current default keymap 



Encode an ANSI string into key codes 

Decode a raw key input event to an ANSI string 

Set the current default keymap for the system 



MapRawKey ( ) 
SetKeyMapDef ault i 



Table 34-2: Console Device Keymap Commands 



CD_ASKKEYMAP 


Ask 


for 


the current console's keymap 




CD_SETKEYMAP 


Set 


the 


current console's keymap 




CD_ASKDEFAULTKEYMAP* 


Set 


the 


current default keymap 




CD_SETDEFAULTKEYMAP** 


Ask 


for 


a pointer to current default 


keymap 













* Obsolete - use AskKeyMapDef ault ( 
** Obsolete - use SetKeyMapDef ault ( 



All of these commands deal with a set of pointers to key translation arrays, known as a KeyMap structure. 
KeyMap structure is defined in <devices/keymap.h> and is shown below. 



The 



struct KeyMap 



UBYTE *km_LoKeyMapTypes; 
ULONG *km_LoKeyMap; 
UBYTE *km_LoCapsable; 
UBYTE *km_LoRepeatable; 
UBYTE *km_HiKeyMapTypes; 
ULONG * km_Hi KeyMap; 
UBYTE *km_HiCapsable; 
UBYTE *km_HiRepeatable; 

}; 

The KeyMap structure contains pointers to arrays which define the ANSI character or string that should be 
produced when a key or a combination of keys are pressed. For example, a keymap might specify that the key 
with raw value hex 20 should produce the ANSI character "a", and if the Shift key is being held it should produce 
the character "A". 

Asking For the Default Keymap 

The AskKeyMapDefaultQ returns a pointer to the current default keymap. To use the mapping functions in 
keymap. library it is normally not necessary to call this function. They accept NULL as equivalent to 'use default 
keymap' and will call this function for you. You can use this pointer for example to cache the system default in 
order to temporarily change the keymap your applications uses, or find the keymap in the keymap. resource list of 
loaded keymaps. You should never change the system wide default keymap unless the user asks you to do so; 
since the Amiga is a multitasking system, changing the keymap could interfere with the behaviour of other 
applications. 
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Setting the Default Keymap 

The system default keymap can be set with the SetKeyMapDefault() function. This function takes a pointer to a 
loaded keymap. In general, this function should never be used by an application unless the application is a 
system Preferences editor, or an application that takes over the system. Normal applications should instead 
attach a console. device unit to their own Intuition window (see the Devices volume), and use the console. device 
command CD_SETKEYMAP to set a keymap only for their own console. 

When making a keymap the system default, first check whether the keymap has been loaded previously by 
checking the keymap list of the keymap. resource. If it has not been loaded already, it can be loaded from 
devs:Keymaps, and added to the keymap list of keymap. resource. This will ensure that other applications which 
may want the keymap will not have to load a second instance. Once made the default, the keymap can never be 
safely removed from memory, even after if it is no longer the default, since other applications may still have and 
use a pointer to it. 



Accessing the Keymap for the Current Console 

The function AskKeyMap() shown below does not return a pointer to a table of pointers to currently assigned key 
mapping. Instead, it copies the current set of pointers to a user-designated area of memory. AskKeyMap() 
returns a TRUE or FALSE value that says whether or not the function succeeded. 

The function SetKeyMap(), also shown below, copies the designated key map data structure to the console 
device. Thus this routine is complementary to AskKeymap() in that it can restore an original key mapping as well 
as establish a new one. 

Ask/SetKeyMap() functions. These functions assume that you have already opened the 
console. device and that request is a valid lOStdReq structure for the newly opened 
console. These functions are not part of the keymap.library, nor of the console. device. These 
merely demonstrate CD_ASKKEYMAP and CD_SETKEYMAP which are console. device 
commands. 

/* These functions require that you have created a port and an 10 request, 

* and have opened the console device as shown in the Console Device 

* chapter of the Devices volume of this manual set. 

*/ 

#include <devices/keymap.h> 

BOOL AskKeyMap (struct IOStdReq *request, struct KeyMap *keymap) 

{ 

request ->io_Command = CD_ASKKEYMAP ; 
request ->io_Length = sizeof (struct KeyMap); 
request ->io_Data = (APTR) keymap; /* where to put it */ 
DoIO (request) ; 

if (request ->io_Error) return (FALSE) ; 
else return (TRUE) ; /* if no error, it worked. */ 
} 

BOOL SetKeyMap (struct IOStdReq *request , struct KeyMap *keymap) 

{ 

request ->io_Command = CD_SETKEYMAP ; 

request ->io_Length = sizeof (struct KeyMap); 

request ->io_Data = (APTR) keymap; /* where to get it */ 

DoIO (request) ; 

if (request ->io_Error) return (FALSE) ; 

else return (TRUE) ; /* if no error, it worked. */ 
} 
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Mapping Key Codes to ANSI Strings 

MapRawKey() is converts raw key codes to ANSI characters based on a default or supplied keymap. 

WORD MapRawKey (struct InputEvent *inputevent, UBYTE *buffer, 
WORD buf f erlength, struct Keymap *keymap) ; 

MapRawKey() takes an IECLASS_RAWKEY inputevent, which may be chained, and converts the key codes to 
ANSI characters which are placed in the specified buffer. If the buffer would overflow, for example because a 
longer string is attached to a key, -1 will be returned. If no error occurred, MapRawKey() will return the number of 
bytes written in the buffer. The keymap argument can be set to NULL if the default keymap is to be used for 
translation, or can be a pointer to a specific KeyMap structure. 

The following example shows how to implement the MapRawKey() function. 

;/* maprawkey.c - Execute me to compile me with SAS C 5.10 

LC -bl -cfistq -v -y -j73 maprawkey.c 

Blink FROM LIB : c . o, maprawkey . o TO maprawkey LIBRARY LIB : LC . lib, LIB : Amiga . lib 

quit 

* maprawkey.c - Map Intuition RAWKEY events to ANSI with MapRawKey () ; 

*/ 

#include <exec/types .h> 
#include <exec/memory . h> 
#include <dos/dos.h> 



#include <intuition/intuition.h> 
#include <devices/inputevent . h> 

#include <clib/exec_protos . h> 
#include <clib/dos_protos . h> 
#include <clib/keymap_protos . h> 
#include <clib/intuition_protos . h> 

#include <stdio.h> 
#include <stdlib.h> 

#ifdef LATTICE 

int CXBRK(void) { return(O); } /* Disable Lattice CTRL/C handling */ 

void chkabort (void) { return; } /* really */ 

#endif 

/* our function prototypes */ 

void openall (void) ; 

void closeall (void) ; 

void closeout (UBYTE *errstring, LONG re); 

struct Library *IntuitionBase = NULL; 
struct Library *KeymapBase = NULL; 
struct Window *window = NULL; 

void main (int argc, char **argv) 

{ 

struct IntuiMessage *imsg; 

APTR *eventptr; 

struct InputEvent inputevent = {o}; 

LONG windowsignal; 

UBYTE buffer [8] ; 

COUNT i ; 

BOOL Done = FALSE; 

openall ( ) ; 

window = OpenWindowTags (NULL, 

WA_Width, 500, 

WA_Height, 60, 

WA_Title, "MapRawKey - Press Keys", 

WA_Flags, WFLG_CLOSEGADGET | WFLG_ACTIVATE , 

WA_IDCMP, IDCMP_RAWKEY | IDCMP_CLOSEWINDOW, 

TAG_DONE) ; 

if (window == NULL) closeout ( "Can' t open window" , RETURN_FAIL) ; 

windowsignal = 1L << window- >UserPort - >mp_SigBit ; 

/* Initialize InputEvent structure (already cleared to 0) */ 
inputevent .ie_Class = IECLASS_RAWKEY; 

while ( !Done) 

{ 

Wait (windowsignal) ; 

while (imsg = (struct IntuiMessage *) GetMsg (window->UserPort) ) 

{ 

switch (imsg->Class) 

{ 
case IDCMP_CLOSEWINDOW: 
Done = TRUE ; 
break; 

case IDCMP_RAWKEY : 

inputevent . ie_Code = imsg->Code; 
inputevent . ie_Qualifier = imsg->Qualif ier ; 

print f ("RAWKEY: Code=$%04x Qualif ier=$%041x\n" , 
imsg->Code, imsg->Qualif ier) ; 

/* Make sure deadkeys and qualifiers are taken 
* into account . 



*/ 

eventptr = imsg->IAddress ; 

inputevent . ie_EventAddress = "eventptr; 

/* Map RAWKEY to ANSI */ 

i = MapRawKey (&inputevent , buffer, 8, NULL); 

if (i == -1) Write (Output (), ""Overflow*" , 10) ; 
else if (i) 

{ 

/* This key or key combination mapped to something */ 

printf ("MAPS TO: ") ; 

Write (Output .buffer, i) ; 

printf ( "\n" ) ; 

} 
break; 



ReplyMsg ( (struct Message *)imsg); 

} 
} 
CloseWindow (window) ; 
closeall ( ) ; 
exit (RETURN OK) ; 



void openall (void) 
{ 

KeymapBase = OpenLibrary ( "keymap. library" , 37); 

if (KeymapBase == NULL) closeout ( "Kickstart 2.0 required" , RETURN_FAIL) ; 

IntuitionBase = OpenLibrary ( "intuition. library" , 37); 

if (IntuitionBase == NULL) closeout ( "Can' t open intuition" , RETURN_FAIL) ; 



} 

void closeall (void) 

{ 

if (IntuitionBase) CloseLibrary (IntuitionBase) ; 

if (KeymapBase) CloseLibrary (KeymapBase) ; 
} 

void closeout (UBYTE *errstring, LONG re) 

{ 

if (*errstring) printf ( "%s\n" , errstring) ; 

closeall ( ) ; 

exit (re) ; 
} 
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Mapping ANSI Strings To Key Codes 

The MapANSIQ function translates ANSI strings into raw key codes, complete with qualifiers and (double) dead 
keys, based on a default or supplied keymap. 

LONG MapANSI (UBYTE "string, LONG stringlength, UBYTE "buffer, 
LONG buf f erlength, struct KeyMap "keymap) ; 

The string argument is a pointer to an ANSI string, of length stringlength. The buffer argument is a pointer to the 
memory block where the translated key codes will be placed. The length of this buffer must be indicated in 
WORDs since each translation will occupy one byte for the key code and one for the qualifier. Since one ANSI 
character can be translated to two dead keys and one key, the buffer must be at least 3 WORDs per character in 
the string to be translated. The keymap argument can be set to NULL if the default keymap is to be used, or can 
be a pointer to a KeyMap structure. Upon return, the function will indicate how many key code/qualifier 
combinations are placed in the buffer or a negative number in case an error occurred. If zero is returned, the 
character could not be translated. 

The following example shows the usage of MapANSIQ and demonstrates how returned key codes can be 
processed. 



;/* mapansi.c - Execute me to compile me with SAS C 5.10 

LC -bl -cfistq -v -y -J73 mapansi.c 

Blink FROM LIB : c . o, mapansi . o TO mapansi LIBRARY LIB : LC . lib, LIB : Amiga . lib 

quit 

mapansi.c - converts a string to input events using MapANSlO function. 

This example will also take the created input events 
and add them to the input stream using the simple 
commodities . library function AddlEvents ( ) . Alternately, 
you could open the input. device and use the input device 
command IND_WRITEEVENT to add events to the input stream. 
*/ 

#include <exec/types . h> 

#include <exec/memory . h> 

#include <exec/io.h> 

#include <dos/dos.h> 

#include <devices/input . h> 

#include <devices/inputevent . h> 

#include <clib/exec_protos . h> 

#include <clib/dos_protos . h> 

#include <clib/keymap_protos . h> 

#include <clib/commodities_protos . h> 

#include <stdio.h> 
#include <stdlib.h> 

#ifdef LATTICE 

int CXBRK(void) { return(O); } /* Disable Lattice CTRL/C handling */ 

void chkabort (void) { return; } /* really */ 

#endif 

struct Library *KeymapBase = NULL; /* MapAnsiO function */ 

struct Library *CxBase = NULL; /* AddlEvents () function */ 

struct InputEvent *InputEvent = NULL; /* we'll allocate this */ 

/* prototypes for our program functions */ 

void openall (void) ; 

void closeall (void) ; 

void closeout (UBYTE *errstring, LONG re); 

void main (int argc, char **argv) 

{ 

UBYTE *string; 

UBYTE *tmpl; 

UBYTE *tmp2; 

UBYTE iebuffer [6] ; /* Space for two dead keys */ 

/* + 1 key + qualifiers */ 



COUNT l ; 

LONG re = 0; 

openall ( ) ; 

string = " ; String converted to input events and sent to input device\n" ; 

InputEvent ->ie_Class ■ IECLASS_RAWKEY; 

/* Turn each character into an InputEvent */ 
tmpl = string; 

while (*tmpl) 

{ 

/* Convert one character, use default key map */ 
i = MapANSI (tmpl, 1, iebuffer, 3, NULL) ; 

/* Make sure we start without deadkeys */ 

InputEvent ->ie_PrevlDownCode = InputEvent ->ie_PrevlDownQual = 0; 

InputEvent ->ie_Prev2DownCode = InputEvent ->ie_Prev2DownQual = 0; 



tmp2 = iebuffer; 

switch (i) 

{ 

case -2 : 

printf ( "Internal error\n", NULL); 

re = RETURN_FAIL; 

break; 

case -1: 

printf ( "Overt low\n" , NULL) ; 

re = RETURN_FAIL; 

break; 

case : 

printf ( "Can' t generate code\n", NULL) ; 
break; 

case 3 : 

InputEvent->ie_Prev2DownCode = *tmp2++; 
InputEvent ->ie_Prev2DownQual = *tmp2++; 
/* FALL THROUGH */ 

case 2 : 

InputEvent ->ie_PrevlDownCode = *tmp2++; 
InputEvent ->ie_PrevlDownQual = *tmp2++; 
/* FALL THROUGH */ 

case 1 : 

InputEvent ->ie_Code = *tmp2++; 
InputEvent ->ie__Qualifier = *tmp2; 
break; 



if (re == RETURNJOK) 

{ 

/* Send the key down event */ 
AddlEvents (InputEvent) ; 

/* Create a key up event */ 

InputEvent ->ie_Code |= IECODE_UP_PREFIX; 

/* Send the key up event */ 
AddlEvents (InputEvent) ; 



if (re != RETURNJOK) 
break; 

tmpl++ ; 



closeall ( ) ; 
exit (re) ; 
} 

void openall (void) 

{ 

KeymapBase = OpenLibrary ( "keymap. library" , 37); 

if (KeymapBase == NULL) closeout ( "Kickstart 2.0 required", RETURN_FAIL) ; 

CxBase = OpenLibrary ( "commodities . library" , 37); 

if (CxBase == NULL) closeout ( "Kickstart 2.0 required", RETURN_FAIL) ; 

InputEvent = AllocMem (sizeof (struct InputEvent), MEMF_CLEAR) ; 

if (InputEvent == NULL) closeout ( "Can' t allocate input event ", RETURN_FAIL) 



void closeall () 

{ 

if (InputEvent) FreeMem (InputEvent , sizeof (struct InputEvent)) 
if (CxBase) CloseLibrary (CxBase) ; 



if (KeymapBase) CloseLibrary (KeymapBase) ; 



void closeout (UBYTE *errstring, LONG re) 
{ 



if (*errstring) 
closeall ( ) ; 
exit (re) ; 



printf ( " %s\n" , errstring) ; 



Details of the Keymaps Structure 

A KeyMap structure contains pointers to arrays which determine the translation from raw key codes to ANSI 
characters. 

struct KeyMap 

{ 

UBYTE *km_LoKeyMapTypes; 
ULONG *km_LoKeyMap; 
UBYTE *km_LoCapsable; 
UBYTE *km_LoRepeatable; 
UBYTE *km_HiKeyMapTypes; 
ULONG *km_Hi KeyMap; 
UBYTE *km_HiCapsable; 
UBYTE *km_HiRepeatable; 

}; 
LoKeyMap and HighKeyMap 

The low key map provides translation of the key values from hex 00-3F; the high key map provides translation of 
key values from hex 40-7F. Key values from hex 68-7F are not used by the existing keyboards, but this may 
change in the future. A raw key value (hex 00-7F) plus hex 80 is the release of that key. If you need to check for 
raw key releases do it like this: 



if (keyvalue & 0x8 0) 
else 



/* do key up processing */ } 
/* do key down processing */ } 
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Raw output from the keyboard for the low key map does not include the space bar, Tab, Alt, Ctrl, arrow keys, and 
several other keys. 

Table 34-3: High Key Map Hex Values 



Key Number Keycap Legend or Function 



40 

41 

42 

43 

44 

45 

46 

4A 

4C 

4D 

4E 

4F 



Space 

Backspace 

Tab 

Enter 

Return 

Escape 

Delete 

Numeric Pad character 

Cursor Up 

Cursor Down 

Cursor Right 

Cursor Left 



Key Number 


Key Legend or Function 


50-59 


Function keys F1-F10 


5A-5E 


Numeric Pad characters 


5F 


Help 


60 


Left Shift 


61 


Right Shift 


62 


Caps Lock 


63 


Control 


64 


Left Alt 


65 


Right Alt 


66 


Left Amiga 


67 


Right Amiga 



The keymap table for the low and high keymaps consists of 4-byte entries, one per hex key code. These entries 
are interpreted in one of three possible ways: 

As four separate bytes, specifying how the key is to be interpreted when pressed alone, with one 
qualifier, with another qualifier, or with both qualifiers (where a qualifier is one of three possible keys: 
Ctrl, Alt, or Shift). 



As a longword containing the address of a string descriptor, where a string of characters is to be output 
when this key is pressed. If a string is to be output, any combination of qualifiers can affect the string that 
may be transmitted. 

As a longword containing the address of a dead-key descriptor, where additional data describe the 
character to be output when this key is pressed alone or with another dead key. 

The keymap tables must be word aligned. The keymap tables must begin aligned on a word 
boundary. Each entry is four bytes long, thereby maintaining word alignment throughout the 
table. This is necessary because some of the entries may be longword addresses and must 
be aligned properly for the 68000. 
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LoKeyMapTypes and HiKeyMapTypes 

The tables named km_LoKeyMapTypes and kmHiKeyMapTypes each contain one byte per raw key code. 
Each byte defines the type of entry that is found in the keymap table for that raw key code. 

Possible key types are: 

Any of the qualifier groupings noted below 

KCF_STRING + any combination of KCF_SHIFT, KCF_ALT, KCF_CONTROL (or KC_NOQUAL) if the 
result of pressing the key is to be a stream of bytes (and key-with-one-or-more-qualifiers is to be one or 
more alternate streams of bytes). 

Any key can be made to output up to eight unique byte streams if KCF_STRING is set in its keytype. The 
only limitation is that the total length of all of the strings assigned to a key must be within the "jump 
range" of a single byte increment. See the "String Output Keys" section below for more information. 

KCF_DEAD + any combination of KCF_SHIFT, KCF_ALT, KCF_CONTROL (or KC_NOQUAL) if the key 
is a dead-class key and can thus modify or be modified by another dead-class key. See the 
"Dead-Class Keys" section below for more information. 

The low keytype table covers the raw key codes from hex 00-3F and contains one byte per key code. Therefore 
this table contains 64 (decimal) bytes. The high keytype table covers the raw key codes from hex 40-7F and 
contains 64 (decimal) bytes. 

More About Qualifiers 

For keys such as the Return key or Esc key, the qualifiers specified in the keytypes table (up to two) are the 
qualifiers used to establish the response to the key. This is done as follows. In the keytypes table, the values 
listed for the key types are those listed for the qualifiers in <devices/keymap.h> and <devices/keymap.i>. 
Specifically, these qualifier equates are: 



KC_NOQUAL 


0x00 


KCF_SHIFT 


0x01 


KCF_ALT 


0x02 


KCF_CONTROL 


0x04 


KC_VANILLA 


0x07 


KCF_DOWNUP 


0x08 


KCF STRING 


0x4 



As shown above, the qualifiers for the various types of keys occupy specific bit positions in the key types control 
byte. As you may have noticed, there are three possible qualifiers, but only a 4-byte space in the table for each 
key. This does not allow space to describe what the computer should output for all possible combinations of 
qualifiers. A solution exists, however, for "vanilla" keys, such as the alphabetic keys. Here is how that works. 
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Keys of type KC_VANILLA use the 4 bytes to represent the data output for the key alone, Shifted key, Alt'ed key, 
and Shifted-and-Alt'ed key. Then for the Ctrl-key-plus-vanilla-key, use the code for the key alone with bits 6 and 5 
set to 0. 



The Vanilla Qualifier Does Not Mean Plain. The qualifier KC_VANILLA is equivalent to 
KCF_SHIFT+KCF_ALT+KCF_CONTROL 

This table shows how to interpret the keymap for various combinations of the qualifier bits: 

Table 34-4: Keymap Qualifier Bits 



Then data at this position in the keytable is 
If Keytype is: output when the key is pressed along with: 

KC_NOQUAL - - - alone 

KCF_SHIFT 

KCF_ALT 

KCF_CONTROL 

KCF_ALT+KCF_SHIFT 

KCF_CONTROL+KCF_ALT 
KCF_CONTROL+KCF_SHIFT 
KC_VANILLA 

*Special case- -Ctrl key, when pressed with one of the alphabet keys and certain others, is to output key-alone value with 
the bits 6 and 5 set to zero . 



- 


- 


Shift 


alone 


- 


- 


Alt 


alone 


- 


- 


Ctrl 


alone 


Shift+Alt 


Alt 


Shift 


alone 


Ctrl+Alt 


Ctrl 


Alt 


alone 


Ctrl+Shift 


Ctrl 


Shift 


alone 


Shift+Alt 


Alt 


Shift 


alone* 



String Output Keys 

When a key is to output a string, the keymap table contains the address of a string descriptor in place of a 4-byte 
mapping of a key. Here is a partial table for a new high keymap table that contains only three entries thus far. The 
first two are for the space bar and the backspace key; the third is for the tab key, which is to output a string that 
says "[TAB]". An alternate string, "[SHIFTED-TAB]", is also to be output when a shifted TAB key is pressed. 



newHiMapTypes : 

DC . B KCF_ALT , KC_NOQUAL , 
DC.B KCF_STRING+KCF_SHIFT 
... ; (more) 
newHiMap : 

DC.B 0,0,$A0,$20 ;key 40 
DC.B 0,0,0, $08 ;key 41 
DC.L newkey42 ;key 42 
... ; (more) 
newkey42 : 

DC.B new4 2ue - new42us 
DC.B new42us - newkey42 



DC.B 
DC.B 

new42us : 
new42ue : 
new42ss : 
new4 2se : 



new4 2se 
new4 2ss 

DC.B 

DC.B 



new42ss 
newkey42 



;key 41 
;key 4 2 



space bar, and Alt -space bar 

Back Space key only 

new string definition to output for Tab 



; length of the unshifted string 

; number of bytes from start of 

; string descriptor to start of this string 

/length of the shifted string 

; number of bytes from start of 

; string descriptor to start of this string 



[TAB] ' 
[SHIFTED-TAB] 
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The new high map table points to the string descriptor at address newkey42. The new high map types table says 
that there is one qualifier, which means that there are two strings in the key string descriptor. 

Each string in the descriptor takes two bytes in this part of the table: the first byte is the length of the string, and 
the second byte is the distance from the start of the descriptor to the start of the string. Therefore, a single string 
(KCF_STRING + KC_NOQUAL) takes 2 bytes of string descriptor. If there is one qualifier, 4 bytes of descriptor 
are used. If there are two qualifiers, 8 bytes of descriptor are used. If there are 3 qualifiers, 16 bytes of descriptor 
are used. All strings start immediately following the string descriptor in that they are accessed as single-byte 
offsets from the start of the descriptor itself. Therefore, the distance from the start of the descriptor to the last 
string in the set (the one that uses the entire set of specified qualifiers) must start within 255 bytes of the 
descriptor address. 

Because the length of the string is contained in a single byte, the length of any single string must be 255 bytes or 
less while also meeting the "reach" requirement. However, the console input buffer size limits the string output 
from any individual key to 32 bytes maximum. 



The length of a keymap containing string descriptors and strings is variable and depends on the number and size 
of the strings that you provide. 

Capsable Bit Tables 

The vectors km_LoCapsable and km_HiCapsable each point to an array of 8 bytes that contain more 
information about the keytable entries. Specifically, if the Caps Lock key has been pressed (the Caps Lock LED is 
on) and if there is a bit on in that position in the capsable map, then this key will be treated as though the Shift key 
is now currently pressed. For example, in the default key mapping, the alphabetic keys are "capsable" but the 
punctuation keys are not. This allows you to set the Caps Lock key, just as on a normal typewriter, and get all 
capital letters. However, unlike a normal typewriter, you need not go out of Caps Lock to correctly type the 
punctuation symbols or numeric keys. 

In the byte array, the bits that control this feature are numbered from the lowest bit in the byte, and from the 
lowest memory byte address to the highest. For example, the bit representing capsable status for the key that 
transmits raw code 00 is bit in byte 0; for the key that transmits raw code 08 it is bit in byte 1 , and so on. 

There are 64 bits (8 bytes) in each of the two capsable tables. 

Repeatable Bit Tables 

The vectors km_LoRepeatable and km_HiRepeatable each point to an array of 8 bytes that contain additional 
information about the keytable entries. A bit for each key indicates whether or not the specified key should repeat 
at the rate set by the Input Preferences program. 

The bit positions correspond to those specified in the capsable bit table. If there is a 1 in a specific position, the 
key can repeat. There are 64 bits (8 bytes) in each of the two repeatable tables. 
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Key Map Standards 

Users and programs depend on certain predictable behaviors from all keyboards and keymaps. With the 
exception of dead-class keys (see "Dead-Class Keys" section), mapping of keys in the low key map should follow 
these general rules: 

When pressed alone, keys should transmit the ASCII equivalent of the unshifted letter or lower symbol 
on the keycap. 

When Shifted, keys should transmit the ASCII equivalent of the shifted letter or upper symbol printed on 
the keycap. 

When Alt'ed, keys should generally transmit the same character (or act as the same deadkey) as the 
Alt'ed key in the usal keymap. 

When pressed with CTRL alone, alphabetic keys should generally transmit their unshifted value but with 
bits 5 and 6 cleared. This allows keyboard typing of "control characters." For example, the C key 
(normally value $63) should transmit value $03 (Ctrl-C) when Ctrl and C are pressed together. 

The keys in the high key map (keys with raw key values $40 and higher) are generally non-alphanumeric keys 
such as those used for editing (backspace, delete, cursor keys, etc.), and special Amiga keys such as the function 
and help keys. Keymaps should translate these keys to the same values or strings as those shown in table 34-6, 
ROM Default Key Mapping. 

In addition to their normal unshifted and shifted values, the following translations are standard for particular 
qualified high keymap keys: 

Generates If Used with Qualifier, 
Key This Value Generates This Value 



Space $2 $A0 with qualifier KCF_ALT 
Return $0D $0A with qualifier KCF_CONTROL 
Esc $1B $9B with qualifier KCF_ALT 



Dead-Class Keys 

All of the national keymaps, including USA, contain dead-class keys. This term refers to keys that either modify or 
can themselves be modified by other dead-class keys. There are two types of dead-class keys: dead and 
deadable. A dead key is one which can modify certain keys pressed immediately following. For example, on the 
German keyboard there is a dead key marked with the grave accent ('). The dead key produces no console 
output, but when followed by (for instance) the A key, the combination will produce the a-grave (a) character 
(National Character Code $E0). On the U.S. keyboard, Alt-G is the deadkey used to add the grave accent (') to 
the next appropriate character typed. A deadable key is one that can be prefixed by a dead key. The A key in the 
previous example is a deadable key. Thus, a dead key can only affect the output of a deadable key. 
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For any key that is to have a dead-class function, whether dead or deadable, the qualifier KCF_DEAD flag must 
be included in the entry for the key in the KeyMapTypes table. The KCF_DEAD type may also be used in 
conjunction with the other qualifiers. Furthermore, the key's keymap table entry must contain the longword 
address of the key's dead-key descriptor data area in place of the usual 4 ASCII character mapping. 

Below is an excerpt from the Amiga 1000 German key map which is referred to in the following discussion. 



KMLowMapType : 

DC.B KCF_DEAD+KC_VANILLA 

DC.B KCF_DEAD+KC_VANILLA 

KMLowMap : DC . L key2 

DC.L key2 5 

. possible dead keys 

key2 5: 

DC.B 0, 'h' , 0, 'H' 

DC . B DPF_DEAD , 3 , DPFJDEAD , 3 

DC.B 0, $08,0, $08,0, $88,0, $8! 

. deadable keys (modified by 

key2 0: ; a, A, ae, AE 

DC.B DPF_MOD,key2 0u-key2 



aA (Key 20) 
(more . . . ) 

hH (Key 25) 
(more . . . ) 

(more . . . ) 
h, H, dead ' 
(more . . . ) 



A, ae, AE 



h, H 
dead 



dead 



control translation 



(more . . 

dead keys) 



DC.B 



DPF_MOD , key2 s - key2 



DC.B 


0, $E6, 0, $C6 






DC.B 


0, $01, 0, $01 


0, $81, 


$81 , 


key2 0u: 


DC.B 


'a' , $E1 


$E0,? 


DC.B 


$E1, $E1, $E2 


$E1, $E1 


$E1 , 


DC.B 


$E0, $E2, $E0 


$E0, $E0 


$E0 , 


key2 0s: 


DC.B 


'A' ,$C1 


$co,S 


DC.B 


$C1,$C1,$C2 


$C1,$C1 


$C1 , 


DC.B 


$C0,$C2,$C0 


$C0,$C0 


$C0 , 



deadable flag, number of 

bytes from start of key2 

descriptor to start of un- 

shifted data 

deadable flag, number of 

bytes from start of key2 

descriptor to start of shift- 
ed data 

null flags followed by rest 

of values (ALT, CTRL...) 
$E2,$E3,$E4 ; 'a' alone and characters 

output when key alone is 

prefixed by a dead key 

most recent is ' 

most recent is ' 
$C2,$C3,$C4 ; SHIFTed 'a' 

output when SHIFTed key is 

prefixed by a dead key 

most recent is ' 

most recent is ' 



and characters to 



In the example, key 25 (the H key) is a dead key and key 20 (the A key) is a deadable key. Both keys use the 
addresses of their descriptor data areas as entries in the LoKeyMap table. The LoKeyMapTypes table says that 
there are four qualifiers for both: the requisite KCFDEAD, as well as KCFSHIFT, KCFALT, and 
KCF_CONTROL. The number of qualifiers determine length and arrangement of the descriptor data areas for 
each key. The next table shows how to interpret the KeyMapTypes for various combinations of the qualifier bits. 
For each possible position a pair of bytes is needed. The first byte in each pair tells how to interpret the second 
byte (more about this below). 
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Table 34-5: Dead Key Qualifier Bits 



| Then the pair of bytes in this position 
| in the dead-class key descriptor data is 
If type is: | output when the key is pressed along with: 


NOQUAL alone - - - | - | 

A | alone |a|-| - |-| - - 1 

C | alone |c|-| - |-| 

S | alone |s|-| - |-| - - ! 

A+C alone AC A+C j - j - - 

A+S alone S A A+S j - j - - 

C+S alone S j C j C+S j - j - j 

S+A+C (VANILLA) alone S A S+A C C+S C+A C+S+A 



The abbreviations A, C, S stand for KCF_ALT, KCF_CONTROL, 
KCF_SHIFT, respectively. Also note that the ordering is 
reversed from that in the normal KeyMap table. 



and 



Because keys 20 and 25 each use three qualifier bits (not including KCF_DEAD), according to the table there 
must be 8 pairs of data, arranged as shown. Had only KCF_ALT been set, for instance, (not including 
KCF_DEAD), just two pairs would have been needed. 

As mentioned earlier, the first byte of each data pair in the descriptor data area specifies how to interpret the 
second byte. There are three possible values: 0, DPF_DEAD and DPF_MOD. In the Amiga 1000 German 
keymap listed above, DPF_DEAD appears in the data for key 25, while DPF_MOD is used for key 20. It is the 
use of these flags that determines whether a dead-class key has dead or deadable function. A value of zero 
causes the unrestricted output of the following byte. 

If the flag byte is DPF_DEAD, then that particular key combination (determined by the placement of the pair of 
bytes in the data table) is dead and will modify the output of the next key pressed (if deadable). How it modifies is 
controlled by the second byte of the pair which is used as an index into part(s) of the data area for ALL the 
deadable (DPF_MOD set) keys. 

Before going further, an understanding of the structure of a descriptor data area wherein DPF_MOD is set for one 
(or more) of its members is necessary. Referring to the example, we see that DPF_MOD is set for the first and 
second pairs of bytes. According to its LoKeyMapTypes entry, and using table 34-5 (Dead Key Qualifier Bits) as 
a guide, these pairs represent the alone and SHIFTed values for the key. When DPF_MOD is set, the byte 
immediately following the flag must be the offset from the start of the key's descriptor data area to the start of a 
table of bytes describing the characters to output when this key combination is preceded by any dead keys. This 
is where the index mentioned above comes in. The value of the index from a prefixing dead key is used to 
determine which of the bytes from the deadable keys special table to output. The byte in the index+1 position is 
sent out. (The very first byte is the value to output if the key was not prefixed by a dead key.) Thus, if Alt-H is 
pressed (dead) and then Shift-A, an 'a' with a circumflex ( A ) accent will be output. This is because: 

The byte pair for the ALT position of the H key (key 25) is DPF_DEAD,3 so the index is 3. 

The byte pair for the SHIFT position of the A key (key 20) is DPF_MOD, key20s-key20, so we refer to 
the table-of-bytes at key20s. 
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The third+1 byte of the table-of-bytes is $C2, an 'a' character. 



A Note About Table Size. The number of bytes in the table-of-bytes for all deadable keys 
must be equal to the highest index value of all dead keys plus 1 . 

Double-Dead Keys 

Double-dead keys are an extension of the dead-class keys explained above. Unlike normal dead keys wherein 
one dead key of type DPF_DEAD can modify a second of type DPF_MOD, double-dead keys employ two 
consecutive keys of type DPF_DEAD to together modify a third of type DPF_MOD. 

For example, the key on the German keyboard labeled with single quotes ( " ) is a double-dead key. When this 
key is pressed alone and then pressed again shifted, there is no output. But when followed by an appropriate 
third key, for example the A key, the three keypresses combine to produce an 'a' with a circumflex ( A ) accent 
(character code $E2). Thus the double-dead pair qualify the output of the A key. 

The system always keeps the last two down key codes for possible further translation. If they are both of type 
DPF_DEAD and the key immediately following is DPF_MOD then the two are used to form an index into the 
(third) key's translation table as follows: 

In addition to the index found after the DPF_DEAD qualifier in a normal dead key, a second factor is included in 
the high nibble of double-dead keys (it is shifted into place with DP_2DFACSHIFT). Its value equals the total 
number of dead key types + 1 in the keymap. This second index also serves as an identifying flag to the system 
that two dead keys can be significant. 

When a key of type DPF_MOD is pressed, the system checks the two key codes which preceded the current one. 
If they were both DPF_DEAD then the most recent of the two is checked for the double-dead index/flag. If it is 
found then a new index is formed by multiplying the value in lower nibble with that in the upper. Then, the lower 
nibble of the least recent DPF_DEAD key is added in to form the final offset. 

Finally, this last value is used as an index into the translation table of the current, DPF_MOD, key. 

The translation table of all deadable (DPF_MOD) keys has [number of dead key types + 1] * [number of double 
dead key types + 1] entries, arranged in [number of double dead key types + 1] rows of [number of dead key 
types + 1] entries. This is because as indices are assigned for dead keys in the keymap, those that are double 
dead keys are assigned the lower numbers. 

Following is a code fragment from the German (d) keymap source: 

keyOC: 

DC.B DPF_DEAD, 1+ ( 6<<DP_2DFACSHIFT) ; dead ' 

DC.B DPF_DEAD,2+ ( 6<<DP_2DFACSHIFT) ; dead ' 

DC . B , ' = ' , , ' + ' ; =, + 

key2 : 

; a, A, ae, AE DC.B DPF_MOD, key2 0u-key2 , DPF_MOD, key2 0s-key2 

DC.B 0,$E6,0,$C6 DC.B , $01 , , $01 , , $81 , , $81 ; control translation 

key2 0u: 

DC.B 'a' , $E1, $E0, $E2, $E3, $E4 

DC.B $E1,$E1,$E2,$E1,$E1,$E1 

DC.B $E0, $E2, $E0, $E0, $E0, $E0 
key2 0s: 

DC.B 'A' , $C1,$C0,$C2,$C3,$C4 

DC.B $C1,$C1,$C2,$C1,$C1,$C1 

DC.B $C0, $C2, $C0, $C0, $C0, $C0 
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Raw keyOC, the German single quotes ( " ) key, is a double dead key. Pressing this key alone, then again while 
the shift key is down will produce no output but will form a double-dead qualifier. The output of key20 (A), a 
deadable key, will consequently be modified, producing an "a" with a circumflex ( A ) accent. The mechanics are as 
follows: 

When keyOC is pressed alone the DPF_DEAD of the first byte pair in the key's table indicates that the 
key as dead. The second byte is then held by the system. 

Next, when keyOC is pressed again, this time with the Shift key down, the DPF_DEAD of the second 
byte pair (recall that the second pair is used because of the SHIFT qualifier) again indicates the key is a 
dead key. The second byte of this pair is also held by the system. 



St 


recent 


is 


■St 


recent 


is 


■St 


recent 


is 


St 


recent 


is 



Finally, when the A key is pressed the system recalls the latter of the two bytes it has saved. The upper 
nibble, $6, is multiplied by the lower nibble, $2. The result, $0C, is then added to the lower nibble of the 
earlier of the two saved bytes, $1 . This new value, $0D, is used as an index into the (unshifted) 
translation table of key20. The character at position $0D is character $E2, an 'a' with a circumflex ( A ) 
accent. 

Note About Double Dead Keys. If only one double-dead key is pressed before a deadable key 
then the output is the same as if the double-dead were a normal dead key. If shifted keyOC is 
pressed on the German keyboard and then immediately followed by key20, the output 
produced is character $E0, ' a '. As before, the upper nibble is multiplied with the lower, 
resulting in $0C. But because there was no second dead-key, this product is used as the final 
index. 
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Keyboard Layout 



The keys with key codes $2B and $30 in the following keyboard diagrams are keys which are present on some 
national Amiga keyboards. 



ESC 

45 




F1 

50 


FJ 

51 


F3 

52 


F4 

53 


F5 

54 






F6 

55 


n 
56 


F3 

57 


F3 

58 


F10 

59 


DEL 
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DO 
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2 

02 


* 

3 

03 


j 

4 

04 


K 
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05 


3 

06 


i 
i 

07 
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03 


3 

09 




DA 


0B 


4 

DC 


i 
0D 


Back 
Space 

41 




lab 

42 


10 


11 


E 

12 


"FT - 

13 


^ 
14 


Y 

15 


u 
16 


1 
17 




ia 


p 
19 


< 
i 

1A 


1 — 

i 

IB 




Ma Id 

5F 




CTRL 

63 


Caps 
Lock 

62 


A 

20 


5 

£1 


22 


F C 

23 I 


4 


H 

25 
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26 


K 

27 


L 

28 


29 


2A 


Hebjm 

44 


4C 




Shit I I 
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31 


X 

32 


c 
33 


34 


35 


N 

36 
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37 


3B 


39 
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3A 
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61 


4F 


4E 






AL 

E 
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66 


40 
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67 
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J 
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3D 
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3E 
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2F 
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OF 


3C 


4A 
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Figure 34-1 : Amiga 1000 Keyboard Showing Key Codes in Hex 



F1 
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F2 
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F3 
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00 


1 

01 


2 

02 


41 
3 

03 


! 

04 


s 

05 


e 

06 


i 

i 




a 
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3 

09 


) 

3 

DA 


0B 


4 

DC 


I 
0D 
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41 




DEL 

46 


He Id 

5F 
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5B 
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5C 


5D 
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42 


4 

10 
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11 


12 


"FT 

13 
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14 


Y 

15 
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16 
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17 


6 

1B 


19 
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1A 


> 
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IB 
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?B | 44 
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4A 
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63 
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La 

6; 
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5 

21 
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L, 
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27 


"T 

28 


29 
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4C 
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2D 
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s 
2F 


4 

5E 


Shi« 

60 


30 
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31 


X 

32 


C 

33 


34 


35 


N 

36 


IV 

37 


■i 

38 


39 


i 
3A 


shin 
61 


+- 

4F 


4D 


4E 


1 
1D 


3 

IE 


3 

1F 
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64 
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66 


4C 


67 
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3 

OF 


3C 



Figure 34-2: Amiga 500/2000/3000 Keyboard Showing Key Codes in Hex 

The default values given above correspond to the values the console device will return when these keys are 
pressed with the keycaps as shipped with the standard American keyboard. 
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Table 34-6: ROM Default (USAO) and USA1 Console Key Mapping 



Raw 




Key 


Keycap 


Number 


Legend 


00 


1 ~ 


01 


1 ! 


02 


2 @ 


03 


3 # 


04 


4 $ 


05 


5 % 


06 


6 '• 


07 


7 & 


08 


8 * 


09 


9 ( 


0A 


) 


OB 


- 


oc 


= + 


OD 




OE 




OF 





10 


Q 


11 


w 


12 


E 


13 


R 


14 


T 


15 


Y 


16 


U 


17 


I 


18 





19 


P 


1A 


[ { 


IB 


] } 


1C 




ID 


1 


IE 


2 


IF 


3 


20 


A 


21 


S 


22 


D 


23 


F 


24 


G 


25 


H 


26 


J 


27 


K 


28 


L 


29 


; : 


2A 


' " 


2B 




2C 




2D 


4 


2E 


5 


2F 


6 


30 





1 


z 


2 


X 


3 


c 


4 


V 


5 


B 


6 


N 


7 


M 


8 


, 


9 




A 


/ 


B 




C 





Unshifted Shifted 

Default Default 

Value Value 



1 (Accent grave) ~ (tilde) 

1 ! 

2 @ 

3 # 

4 $ 

5 % 
6 

7 & 

8 * 

9 ( 
) 

- (Hyphen) _ (Underscore) 



(undefined) 














(Numeric 


pad) 


q 


Q 






w 


w 






e 


E 






r 


R 






t 


T 






y 


Y 






u 


U 






i 


I 






o 


O 






P 

[ 
] 


P 
{ 
} 






(undefined) 








1 


1 


(Numeric 


pad) 


2 


2 


(Numeric 


pad) 


3 


3 


(Numeric 


pad) 


a 


A 






s 


S 






d 


D 






f 


F 






9 


G 






h 


H 






J 


J 






k 


K 






1 


L 






' (single quote) 


'"' 






(not on most 








US keyboards) 








(undefined) 








4 


4 


(Numeric 


pad) 


5 


5 


(Numeric 


pad) 


6 


6 


(Numeric 


pad) 


(not on most 








US keyboards) 
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z 

X 

c 

V 
B 
N 
M 



, (comma) 
. (period) 
/ ? 
(undefined) 



(Numeric pad) 



3D 

3E 
3F 
40 
41 
42 
43 
44 
45 
46 
47 
48 
49 
4A 
4B 
4C 
4D 
4E 



9 


9 


(Space bar) 


20 


Back Space 


08 


Tab 


09 


Enter 


0D 


Return 


0D 


Esc 


IB 


Del 


7F 




(undefined) 




(undefined) 




(undefined) 




(undefined) 


Up arrow 


<CSI>A 


Down arrow 


<CSI>B 


Forward arrow 


<CSI>C 






Fl 


1 


F2 


2 


F3 


3 


F4 


4 


F5 


5 


F6 


6 


F7 


7 


F8 


8 


F9 


9 


F10 


A 

B 


) 


C 


/ 


D 


* 


E 


+ 


F 


HEL 



Backward arrow <CSI>D 



<CSI>0- 
<CSI>1- 
<CSI>2~ 
<CSI>3- 
<CSI>4~ 
<CSI>5- 
<CSI>6~ 
<CSI>7- 
<CSI>8- 
<CSI>9~ 



7 (Numeric pad) 

8 (Numeric pad) 

9 (Numeric pad) 
20 

08 

09 

0D (Numeric pad) 

0D 

IB 
7F 



(Numeric Pad) 



<CSI>T 






<CSI>S 






<CSI> A 


(note blank space 




after <CSI>) 


<CSI> @ 


(note blank space 




after <CSI>) 


<CSI>10- 






<CSI>11- 






<CSI>12- 






<CSI>13- 






<CSI>14- 






<CSI>15- 






<CSI>16- 






<CSI>17- 






<CSI>18- 






<CSI>19- 






( (usal 


Numeric 


pad) 


) (usal 


Numeric 


pad) 


/ (usal 


Numeric 


pad) 


* (usal 


Numeric 


pad) 


+ (usal 


Numeric 


pad) 


<CSI>?~ 
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Raw 

Key 

Number 



Function 
or Keycap 
Legend 



60 

61 

62 

63 

64 

65 

66 

67 

68 

69 

6A 

6B 

6C 

6D 

6E 

6F 

70-7F 

80-F8 



FA 
FB 



FC 
FD 



Shift (left of space bar) 
Shift (right of space bar) 
Caps Lock 
Ctrl 

(Left) Alt 
(Right) Alt 

Amiga (left of space bar) 
Amiga (right of space bar) 
Left mouse button (not converted) 
Right mouse button (not converted) 
Middle mouse button (not converted) 
(undefined) 
(undefined) 
(undefined) 
(undefined) 
(undefined) 
(undefined) 

Up transition (release or unpress key of one 
of the above keys) (80 for 00, F8 for 7F) 
Last key code was bad 
(was sent in order to resynchronize) 
Keyboard buffer overflow 
(undefined, reserved for 
keyboard processor catastrophe) 
Keyboard selftest failed 
Power-up key stream start. 
Keys pressed or stuck at power-up 
will be sent between FD and FE . 



Left Amiga 

Right Amiga 

Inputs are only for the 

mouse connected to 

Intuition, (currently 

gameport one) . 



FE 

FF 
FF 



Power-up key stream end 
(undefined, reserved) 
Mouse event, movement only, 
no button change (not converted) 



Notes about the preceding table: 

1) "<CSI>" is the Control Sequence Introducer, value hex 9B. 

2) "(undefined)" indicates that the current keyboard design should not generate this number. If you are 
using SetKeyMap() to change the key map, the entries for these numbers must still be included. 

3) "(not converted)" refers to mouse button events. You must use the sequence "<CSI>2{" to inform the 
console driver that you wish to receive mouse events; otherwise these will not be transmitted. 

4) "(RESERVED)" indicates that these key codes have been reserved for national keyboards. The $2B 
code key will be between the double-quote (") and Return keys. The $30 code key will be between the 
Shift and Z keys. 
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+ 




























































1 


1 


1 


1 


1 


1 


i 


1 






[ 











1 


1 


1 


1 














1 


1 


i 


1 






[ 





1 


1 








1 


1 








1 


1 








i 


1 






| 


1 





1 





1 





1 





1 





1 





1 





1 






00 | 


01 


02 


03 


04 


05 


06 


07 


08 


09 


0a 


0b 


0c 


Od 


0e 


Of 


| 0000 


00 


































0001 


10 


































| 0010 


20 


SP| 


1 


II 


# 


$ 


% 


& 


' 


( 


) 


* 


+ 


/ 


- 




/ 


0011 


30 


[ 


1 


2 


3 


4 


5 


6 


7 


8 


9 




; 


< 


= 


> 


■? 


0100 


40 





A 


B 


C 


D 


E 


F 


G 


H 


I 


J 


K 


L 


M 


N 





0101 


50 


p 


Q 


R 


S 


T 


U 


V 


W 


X 


Y 


z 


[ 


\ 


] 


A. 




| 0110 


60 


1 


a 


b 


c 


d 


e 


f 


g 


h 


i 


j 


k 


1 


m 


n 


o 


| 0111 


70 


p [ 


q 


r 


s 


t 


u 


V 


w 


X 


Y 


z 


{ 




} 


~ 




| 1000 


80 


































1001 


90 


































1010 


aO 


NBSP 


i 


* 


£ 


ts 


¥ 




§ 




© 


a 


« 


-i 


SHY 


® 


— 


1011 


bO 





± 


2 


3 


■* 


U 


1 


• 




i 


° 


» 


X 


a 


% 


£ 


1100 


cO 


A 


A 


A 


A 


A 


A 


E 


Q 


E 


E 


E 


E 


i 


i 


i 


I 


| 1101 


dO 


B 


N 


6 


6 


6 


6 


6 


X 





U 


U 


U 


u 


Y 


i> 


S 


| 1110 


eO 


a 


a 


a 


a 


a 


a 


35 


? 


e 


e 


e 


e 


I 


1 


i 


i 


1111 


fO 


a 


n 


6 


6 


6 


6 


6 


- 





u 


u 


u 


u 


y 


P 


y 



Figure 34-3: ECMA-94 Latinl International 8-Bit Character Set 



Function Reference 



The following chart gives a brief desription of the functions covered in this chapter. All of these functions require 
Release 2 or a later version of the Amiga operating system. See the Amiga ROM Kernel Reference Manual: 
Includes and Autodocs for details on each function call. 

Table 34-7: Keymap Library Functions 



Function 


Description 


AskKeyMapDefault() 


Get a pointer to the current system default keymap 


MapANSIO 


Convert ANSII string to raw key events 


MapRawKey() 


Convert raw key events to ANSII 


SetKeyMapDefault() 


Set the system default keymap 
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Chapter 35 
Math Libraries 



This chapter describes the structure and calling sequences required to access the Motorola Fast Floating Point 
(FFP), the IEEE single-precision math libraries and the IEEE double-precision math libraries via the 
Amiga-supplied interfaces. 

In its present state, the FFP library consists of three separate entities: the basic math library, the transcendental 
math library, and C and assembly-language interfaces to the basic math library plus FFP conversion functions. 
The IEEE single-precision, introduced in Release 2, and the double-precision libraries each presently consists of 
two entities: the basic math library and the transcendental math library. 

Open Each Library Separately. Each Task using an IEEE math library must open the library 
itself. Library base pointers to these libraries may not be shared. Libraries can be context 
sensitive and may use the Task structure to keep track of the current context. Sharing of 
library bases by Tasks may seem to work in some systems. This is true for any of the IEEE 
math libraries. 

Depending on the compiler used, it is not always necessary to explicitly call the library functions for basic floating 
point operations as adding, subtracting, dividing, etc. Consult the manual supplied with the compiler for 
information regarding the compiler options for floating point functions. 

Math Libraries and Functions 

There are six math libraries providing functions ranging from adding two floating point numbers to calculating a 
hyperbolic cosine. They are: 

mathffp.library 

the basic function library 

mathtrans.library 
the FFP transcendental math library 

mathieeesingbas. library 
the IEEE single-precision library 
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mathieesingtrans. library 
the IEEE single-precision transcendental library 

mathieeedoubbas. library 
the IEEE double-precision library 

mathieesingtrans. library 
the IEEE double-precision transcendental library 

FPP Floating Point Data Format 

FFP floating-point variables are defined within C by the float or FLOAT directive. In assembly language they are 
simply defined by a DC.L/DS.L statement. All FFP floating-point variables are defined as 32-bit entities 
(longwords) with the following format: 



MMMMMMMM MMMMMMMM MMMMMMMM EEEEEEE 
31 23 15 7 



The mantissa is considered to be a binary fixed-point fraction; except for 0, it is always normalized (the mantissa 
is shifted over and the exponent adjusted, so that the mantissa has a 1 bit in its highest position). Thus, it 
represents a value of less than 1 but greater than or equal to 1/2. 

The sign bit is reset (0) for a positive value and set (1) for a negative value. 

The exponent is the power of two needed to correctly position the mantissa to reflect the number's true arithmetic 
value. It is held in excess-64 notation, which means that the two's-complement values are adjusted upward by 
64, thus changing $40 (-64) through $3F (+63) to $00 through $7F. This facilitates comparisons among 
floating-point values. 

The value of is defined as all 32 bits being 0s. The sign, exponent, and mantissa are entirely cleared. Thus, 0s 
are always treated as positive. 

The range allowed by this format is as follows: 

DECIMAL: 

9.22337177 * 10 18 > +VALUE > 5.42101070 * W 20 
-9.22337177 * 10 w < -VALUE < -2.71050535 * W 20 

BINARY (HEXADECIMAL): 

.FFFFFF*2 63 > +VALUE > .800000 * 2 63 
-.FFFFFF * 2 s3 < -VALUE < -.800000 * 2 64 

Remember that you cannot perform any arithmetic on these variables without using the fast floating-point libraries. 
The formats of the variables are incompatible with the arithmetic format of C-generated code; hence, all 
floating-point operations are performed through function calls. 
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FFP Basic Mathematics Library 

The FFP basic math library contains entries for the basic mathematics functions such as add, subtract and divide. 
It resides in ROM and is opened by calling OpenLibraryQ with "mathffp. library" as the argument. 

#include <exec/types . h> 
#include <libraries/mathf fp.h> 
#include <clib/mathf fp_protos . h> 

struct Library *MathBase; 
VOID main() 

{ 

if (MathBase = OpenLibrary ( "mathffp . library" , 0)) 



CloseLibrary (MathBase) ; 

} 
else 

printf ( "Can' t open mathffp. library\n" ) ; 
} 

The global variable MathBase is used internally for all future library references. 

FFP Basic Functions 

SPAbS() FLOAT SPAbs ( FLOAT parm ) ; 

Take absolute value of FFP variable. 

SPAdd() FLOAT SPAdd( FLOAT leftParm, FLOAT rightParm) ; 
Add two FFP variables. 



SPCeil() FLOAT SPCeil ( FLOAT parm ) ; 

Computer largest integer less than or equal to variable. 

SPCmp() LONG SPCmp( FLOAT leftParm, FLOAT rightParm); 
Compare two FFP variables. 

SPDiv() FLOAT SPDiv( FLOAT leftParm, FLOAT rightParm); 
Divide two FFP variables. 

SPFix() LONG SPFix ( FLOAT parm ) ; 
Convert FFP variable to integer. 

SPFl00r() FLOAT SPFloor ( FLOAT parm ) ; 

Compute least integer greater than or equal to variable. 

SPFIt() FLOAT SPFlt ( long integer ) ; 
Convert integer variable to FFP. 

SPMul() FLOAT SPMul ( FLOAT leftParm, FLOAT rightParm) ; 
Multiply two FFP variables. 

SPNeg() FLOAT SPNeg ( FLOAT parm ) ; 

Take two's complement of FFP variable. 

SPSub() FLOAT SPSub ( FLOAT leftParm, FLOAT rightParm) ; 

Subtract two FFP variables. 

Math Libraries 835 
SPTst() LONG SPTst ( FLOAT parm ) ; 

Test an FFP variable against zero. 
Be sure to include the proper data type definitions shown below. 

#include <exec/types . h> 
#include <libraries/mathf fp.h> 

#include <clib/mathf fp_protos . h> 
struct Library *MathBase; 
VOID main() 

{ 

FLOAT fl, f2, f3; 

LONG i 1 ; 

if (MathBase = OpenLibrary ( "mathff p. library" , 0)) 

{ 

il = SPFix(fl); /* Call SPFix entry */ 

fl = SPFlt (il); /* Call SPFlt entry */ 

if (SPCmp(f 1, f2) ) {}; /* Call SPCmp entry */ 
if (! (SPTst (fl) ) ) {}; /* Call SPTst entry */ 

fl = SPAbs(f2); /* Call SPAbs entry */ 

fl = SPNeg(f2); /* Call SPNeg entry */ 



fl = SPAdd(f2, f3) 

fl = SPSub(f2, f3) 

fl = SPMul (f 2, f3) 

fl = SPDiv(f2, f3) 



/* Call SPAdd entry */ 

/* Call SPSub entry */ 

/* Call SPMul entry */ 

/* Call SPDiv entry */ 



fl = SPCeil (f2); /* Call SPCeil entry */ 

fl = SPFloor(f2); /* Call SPFloor entry */ 

CloseLibrary (MathBase) ; 

} 
else 

printf ( "Can' t open mathf fp. library\n" ) ; 
} 

The assembly language interface to the FFP basic math routines is shown below, including some details about 



how the system flags are affected by each operation. The access mechanism is: 

MOVEA.L _MathBase,A6 
JSR LVOSPFix(A6) 





FFP Basic Assembly Functions 




Function 


Input Output 


Condition Codes 


LVOSPAbs 


D0=FFP arg | D0=FFP absolute 


N=0 




value 


Z=l if result 
is zero 

v=o 

C=undef ined 
X=undef ined 


LVOSPAdd 


D1=FFP argl | D0=FFP addition 


N=l if result 




D0=FFP arg2 | of argl + arg2 


is negative 
Z=l if result 

is zero 
V=l if result 

overflowed 
C=undef ined 
Z=undef ined 
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Function 



FFP Basic Assembly Functions 
Input Output 



Condition Codes 



_LVOSPCeil D0=FFP arg D0=least integer N=l if result 

| >=arg is negative 

| Z=l if result 

is zero 

i V=undefined 

i C=undefined 

| Z=undefined 


_LVOSPCmp D1=FFP argl D0=+1 if argl>arg2 N=0 

| D0=FFP arg2 | D0=-1 if argl<arg2 Z=l if result 
| D0=0 if argl=arg2 is zero 

! 1 v=0 

: | C=undefined 
i X=undefined 
; | GT=arg2>argl 
I | GE=arg2>=argl 
! | EQ=arg2=argl 

| NE=arg2oargl 
| LT=arg2<argl 
LE=arg2<=argl 


LVOSPDiv | D1=FFP argl | D0=FFP division N=l if result 

| D0=FFP arg2 | of arg2/argl is negative 

| Z=l if result 
i is zero 
; V=l if result 
! overflowed 
i C=undefined 



i Z=undefined 


_LVOSPFix DO=FFP arg DO=Integer N=l if result 

(two's complement) is negative 
1 | Z=l if result 

is zero 
| V=l if overflow 
occurred 
l [ C=undefined 
' X=undefined 


LVOSPFloor | D0=FFP arg | DO=largest integer N=l if result 

| <= arg is negative 

| Z=l if result 
! is zero 

V=undefined 
l [ C=undefined 
i Z=undefined 


_LVOSPFlt DO=Integer D0=FFP result N=l if result 

(two's i is negative 
| complement) | Z=l if result 
1 is zero 
! | v=o 
i [ C=undefined 
i X=undefined 


_LVOSPMul D0=FFP argl D0=FFP N=l if result 

| D1=FFP arg2 | multiplication is negative 
I of argl*arg2 | Z=l if result 
! is zero 

V=l if result 
i overflowed 
i [ C=undefined 
; Z=undefined 
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Function 



FFP Basic Assembly Functions 
Input Output 



Condition Codes 



_LVOSPNeg 


D0 = 


= FFP 


arg 


D0 = 


= FFP 


negated 


N= 
Z-- 

v= 


= 1 

= 1 
= 


if 
is 
if 
is 


result 
negative 
result 
zero 
















c= 


= undefined 
















x= 


= undefined 


LVOSPSub 


Dl= 


= FFP 


argl 


D0 = 


= FFE 


subtraction 


N= 


= 1 


if 


result 




D0 = 


= FFP 


arg2 




of 


arg2-argl 


Z-- 

v= 


= 1 
= 1 


is 

if 
is 
if 


negative 
result 
zero 
result 




















overflowed 
















c= 


= undefined 
















Z = 


= undefined 


_LVOSPTst 


Dl = 


= FFP 


arg 


D0 = 
D0 = 


= + 1 
= -1 


if arg>0 . 
if arg<0 . 


N= 


= 1 


if 
is 


result 
negative 



Note: This 
routine 
trashes the 
arg in Dl . 



D0=0 if arg=0.0 



Z=l if result 

is zero 
V=0 

C=undef ined 
X=undef ined 
EQ=arg=0 . 
NE=arg<>0 . 
PL=arg>=0 . 
MI=arg<0 . 



FFP Transcendental Mathematics Library 

The FFP transcendental math library contains entries for the transcendental math functions sine, cosine, and 
square root. It resides on disk and is opened by calling OpenLibraryQ with "mathtrans.library" as the argument. 

#include <exec/types . h> 
#include <libraries/mathf fp.h> 

#include <clib/mathf fp_protos . h> 
#include <clib/mathtrans_protos . h> 

struct Library *MathTransBase; 
VOID main() 

{ 

if (MathTransBase = OpenLibrary ( "mathtrans . library" , 0) ) 

{ 



CloseLibrary (MathTransBase) 



else 

print f ( "Can' t open mathtrans . library\n" ) ; } 

The global variable MathTransBase is used internally for all future library references. Note that the 
transcendental math library is dependent upon the basic math library, which it will open if it is not open already. If 
you want to use the basic math functions in conjunction with the transcendental math functions however, you 
have to specifically open the basic math library yourself. 
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FFP Transcendental Functions 

SPAsin() FLOAT SPAsin( FLOAT parm ); 
Return arccosine of FFP variable. 

SPAC0S() FLOAT SPAcos ( FLOAT parm ) ; 
Return arctangent of FFP variable. 

SPAtan() FLOAT SPAtan ( FLOAT parm ) ; 
Return arcsine of FFP variable. 

SPSin() FLOAT SPSin( FLOAT parm ); 

Return sine of FFP variable. This function accepts an FFP radian argument and returns the 
trigonometric sine value. For extremely large arguments where little or no precision would result, the 
computation is aborted and the "V" condition code is set. A direct return to the caller is made. 

SPCOS() FLOAT SPCOS ( FLOAT parm ) ; 

Return cosine of FFP variable. This function accepts an FFP radian argument and returns the 
trigonometric cosine value. For extremely large arguments where little or no precision would result, the 
computation is aborted and the "V" condition code is set. A direct return to the caller is made. 



SPTan() FLOAT SPTan ( FLOAT parm ) 
Return tangent of FFP variable. 



This function accepts an FFP radian argument and returns the 



trigonometric tangent value. For extremely large arguments where little or no precision would result, 
the computation is aborted and the "V" condition code is set. A direct return to the caller is made. 

SPSiriCOS() FLOAT SPSincosf FLOAT *cosResult, FLOAT parm); 

Return sine and cosine of FFP variable. This function accepts an FFP radian argument and returns the 
trigonometric sine as its result and the trigonometric cosine in the first parameter. If both the sine 
and cosine are required for a single radian value, this function will result in almost twice the execution 
speed of calling the SPSin() and SPCos() functions independently. For extremely large arguments 
where little or no precision would result, the computation is aborted and the "V" condition code is set. A 
direct return to the caller is made. 

SPSinh() FLOAT SPSinh( FLOAT parm ); 
Return hyperbolic sine of FFP variable. 

SPCOSh() FLOAT SPCosh( FLOAT parm ); 

Return hyperbolic cosine of FFP variable. 

SPTanh() FLOAT SPTanh( FLOAT parm ) ; 

Return hyperbolic tangent of FFP variable. 

SPExp() FLOAT SPExp ( FLOAT parm ) ; 

Return e to the FFP variable power. This function accepts an FFP argument and returns the result 
representing the value of e (2.71828...) raised to that power. 

SPLog() FLOAT SPLog ( FLOAT parm ) ; 

Return natural log (base e) of FFP variable. 

SPLog10() FLOAT SPLoglO( FLOAT parm ); 

Return log (base 10) of FFP variable. 
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SPPOW() FLOAT SPPow( FLOAT power, FLOAT arg ); 

Return FFP arg2 to FFP argl. 

SPSqrt() FLOAT SPSqrt ( FLOAT parm ) ; 

Return square root of FFP variable. 

SPTieee() FLOAT SPTieee ( FLOAT parm ) ; 
Convert FFP variable to IEEE format 

SPFieee() FLOAT SPFieee ( FLOAT parm ) ; 
Convert IEEE variable to FFP format. 

Be sure to include proper data type definitions, as shown in the example below. 

#include <exec/types . h> 
#include <libraries/mathf fp.h> 

#include <clib/mathf fp_protos . h> 
#include <clib/mathtrans_protos . h> 

struct Library *MathTransBase; 

VOID main() 

{ 

FLOAT fl, f2, f3; 

FLOAT il; 

if (MathTransBase = OpenLibrary ( "mathtrans . library" , 33) ) 

{ 

fl = SPAsin(f2); /* Call SPAsin entry */ 

fl = SPAcos(f2); /* Call SPAcos entry */ 

fl = SPAtan(f2); /* Call SPAtan entry */ 

fl = SPSin(f2); /* Call SPSin entry */ 

fl = SPCos(f2); /* Call SPCos entry */ 



fl = SPTan(f2); /* Call SPTan entry */ 

fl = SPSincos (&f3, f2) ; /* Call SPSincos entry */ 



fl = SPSinh(f2) 
fl = SPCosh(f2) 
fl = SPTanh(f2) 



fl 


= SPExp(f2) ; 


fl 


= SPLog(f2) ; 


fl 


= SPLoglO (f2) ; 


fl 


= SPPow(f2) ; 


fl 


= SPSqrt (f2) ; 


il 


= SPTieee (f2) ; 


fl 


= SPFieee (il) ; 



/* Call SPSinh entry */ 

/* Call SPCosh entry */ 

/* Call SPTanh entry */ 

/* Call SPExp entry */ 

/* Call SPLog entry */ 

/* Call SPLoglO entry */ 

/* Call SPPow entry */ 

/* Call SPSqrt entry */ 

/* Call SPTieee entry */ 

/* Call SPFieee entry */ 



CloseLibrary (MathTransBase) ; 



else 

printf ( "Can' t open mathtrans . library\n" ) ; 
} 

The Amiga assembly language interface to the FFP transcendental math routines is shown below, including some 
details about how the system flags are affected by the operation. This interface resides in the library file amiga.lib 
and must be linked with the user code. Note that the access mechanism from assembly language is: 



MOVEA.L _MathTransBase,A6 
JSR _LVOSPAsin(A6) 
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Function 



FFP Transcendental Assembly Functions 
Input Output Condition Codes 



_LVOSPAsin D0=FFP arg D0=FFP arcsine N=0 

radian | Z = l if result 

is zero 
! v=o 

[ C=undefined 
X=undefined 


LVOSPAcos [ D0=FFP arg | D0=FFP arccosine N=0 

i radian | Z = l if result 
! is zero 

V=l if overflow 
occurred 
i | C=undefined 

X=undefined 


_LVOSPAtan D0=FFP arg D0=FFP arctangent N=0 

radian | Z = l if result 
1 is zero 
! | V=0 
1 C=undefined 
; X=undefined 


_LVOSPSin D0=FFP arg D0=FFP sine N=l if result 

in radians 1 is negative 
i | Z=l if result 

I is zero 

V=l if result 
j is meaningless 
i (input magnitude 

too large) 



| C=undefined 
X=undefined 


_LVOSPCos DO=FFP arg DO=FFP cosine N=l if result 

in radians is negative 

| Z=l if result 
! is zero 
i V=l if result 
! is meaningless 

(input magnitude 
too large) 
i j C=undefined 

X=undefined 


_LVOSPTan D0=FFP arg D0=FFP tangent N=l if result 

in radians is negative 
i | Z=l if result 

is zero 
1 V=l if result 
: 1 is meaningless 
i (input magnitude 
! too large) 

| C=undefined 
1 X=undefined 


_LVOSPSincos D0=FFP arg D0=FFP sine N=l if result 

in radians (D1)=FFP cosine is negative 
| Dl=Address I | Z=l if result 

to store is zero 
| cosine result V=l if result 

| is meaningless 
(input magnitude 
too large) 
i C=undefined 

X=undefined 
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FFP Transcendental Assembly Functions 
Input Output Condition Codes 



Function 



LVOSPSinh 


D0=FFP arg 


D0=FFP hyperbolic 


N=l 


if result 




in radians 


sine 


Z = l 
V=l 


is negative 
if result 
is zero 
if overflow 
occurred 








C=undef ined 








X=undef ined 


LVOSPCosh 


D0=FFP arg 


D0=FFP hyperbolic 


N=l 


if result 




in radians 


cosine 


Z = l 
V=l 


is negative 
if result 
is zero 
if overflow 
occurred 








C=undef ined 








X=undef ined 


LVOSPTanh 


D0=FFP arg 


D0=FFP hyperbolic 


N=l 


if result 




in radians 


tangent 




is negative 



| Z=l if result 
i is zero 
1 V=l if overflow 

occurred 
! | C=undefined 

X=undefined 


_LVOSPExp D0=FFP arg D0=FFP exponential N=0 

i | Z=l if result 

is zero 
V=l if overflow 
i occurred 

| C=undefined 
| Z=undefined 


_LVOSPLog D0=FFP arg D0=FFP natural N=l if result 

logarithm is negative 
| Z=l if result 
is zero 
: V=l if arg is 
j | negative or zero 

j C=undefined 
' Z=undefined 


_LVOSPLoglO D0=FFP arg D0=FFP logarithm N=l if result 

(base 10) is negative 
Z=l if result 
i is zero 

|v=l if arg is 
[ negative or zero 
C=undefined 
Z=undefined 


_LVOSPPow D0=FFP D0=FFP result of N=0 

exponent value | arg taken to | Z=l if result 
[ D1=FFP exp power is zero 
| arg value | V=l if result 

overflowed 
! I or arg < 
! [ C=undefined 

Z=undefined 


_LVOSPSqrt D0=FFP arg D0=FFP square root N=0 

i | Z=l if result 

is zero 
V=l if arg was 
1 negative 

| C=undefined 
i | Z=undefined 
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FFP Transcendental Assembly Functions 



Function 



Input 



Output 



Condition Codes 



LVOSPTieee 



D0=FFP 
format arg 



D0=IEEE 

floating-point 
format 



N=l if result 

is negative 

Z=l if result 
is zero 

V=undef ined 

C=undef ined 



LVOSPFieee 



D0=IEEE 
floating-point 
format arg 



D0=FFP format 



Z=undef ined 



N=undef ined 
Z=l if result 

is zero 
V=l if result 

overflowed 
C=undef ined 
Z=undef ined 



FFP Mathematics Conversion Library 

The FFP mathematics conversion library provides functions to convert ASCII strings to their FFP equivalents and 
vice versa. 

It is accessed by linking code into the executable file being created. The name of the file to include in the library 
description of the link command line is amiga.lib. When this is included, direct calls are made to the conversion 
functions. Only a C interface exists for the conversion functions; there is no assembly language interface. The 
basic math library is required in order to access these functions. 

#include <exec/types .h> 
#include <libraries/mathf fp.h> 

#include <clib/mathf fp_protos . h> 

struct Library *MathBase; 

VOID main() 

{ 

if (MathBase = OpenLibrary ( "mathff p. library" , 33)) 

{ 



CloseLibrary (MathBase) ; 

} 
else 



} 



printf ( "Can' t open mathf fp. library\n" ) ; 



Math Support Functions 

afp() FLOAT af p ( BYTE *string ); 

Convert ASCII string into FFP equivalent. 

arnd() VOID arnd( LONG place, LONG exp, BYTE *string) ; 
Round ASCII representation of FFP number. 

dbf() FLOAT dbf ( ULONG exp, ULONG mant); 

Convert FFP dual-binary number to FFP equivalent. 
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fpa() LONG f pa ( FLOAT fnum, BYTE *string); 
Convert FFP variable into ASCII equivalent. 

Be sure to include proper data type definitions, as shown in the example below. Print statements have been 
included to help clarify the format of the math conversion function calls. 

#include <exec/types .h> 
#include <libraries/mathf fp.h> 

#include <clib/mathf fp_protos .h> 
#include <clib/alib_protos .h> 



struct Library *MathBase; 



UBYTE stl [80] ■ "3.1415926535897"; 
UBYTE st2 [80] = "2.7182 8182 8459045"; 
UBYTE st3 [80] , St4 [80] ; 

VOID main() 

{ 

FLOAT numl , num2 ; 

FLOAT nl , n2 , n3 , n4 ; 

LONG expl , exp2 , exp3 , exp4 ; 

LONG mantl, mant2 , mant3, mant4; 

LONG placel, place2 ; 

if (MathBase = OpenLibrary ( "mathff p. library" 
{ 



33)) 



nl = afp(stl); /* Call afp entry */ 

n2 = afp(st2); /* Call afp entry */ 

printf ( "\n\nASCII %s converts to floating point %f", stl, nl) 

printf ( "\nASCII %s converts to floating point %f", st2, n2); 



numl = 3.1415926535897; 
num2 = 2.718281828459045; 

expl = f pa (numl, st3); /* Call fpa entry */ 
exp2 = fpa (num2 , st4); /* Call fpa entry */ 
printf ( "\n\nf loating point %f converts to ASCII %s 
printf ( "\nfloating point %f converts to ASCII %s", 

placel = -2; 

place2 = -1; 

arnd (placel , expl, st3) ; /* Call arnd entry */ 

arnd(place2, exp2 , st4); /* Call arnd entry */ 

printf ( "\n\nASCII round of %f to %d places yields ; 

printf ( "\nASCII round of %f to %d places yields %s 



1 , numl , st3) ; 
num2 , st4) ; 



", numl, placel, st3) 
num2 , place2 , st4); 



expl 


= -3; exp2 = 3; 


exp3 = -3; 


exp4 


= 3; 


mantl = 


= 12345; mant2 = 


-54321; mant3 = 


-12345; 


mant4 



54321; 



nl - dbf (expl, mantl) 
n2 = dbf(exp2, mant2) 
n3 = dbf (exp3, mant3) 
n4 = dbf(exp4, mant4) 
printf ( "\n\ndbf of exp 
printf ( "\ndbf of exp = 
printf ( "\ndbf of exp = 
printf ( "\ndbf of exp = 



/* Call dbf entry */ 

/* Call dbf entry */ 

/* Call dbf entry */ 

/* Call dbf entry */ 
= %d and mant = %d yields FFP number of %f 
%d and mant = %d yields FFP number of %f", 
%d and mant = %d yields FFP number of %f", 
%d and mant = %d yields FFP number of %f", 



, expl, mantl, nl) 
exp2 , mant 2, n2) 
exp3 , mant 3, n3) 
exp4 , mant4 , n4 ) 



CloseLibrary (MathBase) ; 
} 



else 



printf ( "Can' t open mathf f p. library \n" ) ; 
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IEEE Single-Precision Data Format 

The IEEE single-precision variables are defined as 32-bit entities with the following format: 



SEEEEEEE 
31 



MMMMMMMM 
23 



MMMMMMMM 
15 



MMMMMMMM 
7 



Hidden Bit In The Mantissa. There is a "hidden" bit in the mantissa part of the IEEE numbers. 
Since all numbers are normalized, the integer (high) bit of the mantissa is dropped off. The 
IEEE single-precision range is 1 .3E-38 (1 .4E-45 de-normalized) to 3.4E+38. 



The exponent is the power of two needed to correctly position the mantissa to reflect the number's true arithmetic 
value. If both the exponent and the mantissa have zero in every position, the value is zero. If only the exponent 



has zero in every position, the value is an unnormal (extremely small). If all bits of the exponent are set to 1 the 
value is either a positive or negative infinity or a Not a Number (NaN). NaN is sometimes used to indicate an 
uninitialized variable. 

IEEE Single-Precision Basic Math Library 

The ROM-based IEEE single-precision basic math library was introduced in V36. This library contains entries for 
the basic IEEE single-precision mathematics functions, such as add, subtract, and divide. (Note, registered 
developers can license a disk-based version of this library from CATS, for usage with V33). 

The library is opened by making calling OpenLibraryQ with "mathieeesingbas. library" as the argument. Do not 
share the library base pointer between tasks ~ see note at beginning of chapter for details. 

#include <exec/types .h> 

# include <libraries/mathieeesp.h> 

#include <clib/mathsingbas_protos . h> 

struct Library *MathIeeeSingBasBase; 

VOID main() 

{ 

/* do not share base pointer between tasks. */ 
if (MathleeeSingBasBase = OpenLibrary ( "mathieeesingbas . library" , 37)) 

{ 



CloseLibrary (MathleeeSingBasBase) ; 

} 
else 

printf ( "Can' t open mathieeesingbas . library\n" ) ; 
} 

The global variable MathleeeSingBasBase is used internally for all future library references. 

If an 680X0/68881/68882 processor combination is available, it will be used by the IEEE single-precision basic 
library instead of the software emulation. Also, if an autoconfigured math resource is available, that will be used. 
Typically this is a 68881 designed as a 16 bit I/O port, but it could be another device as well. 
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SP IEEE Basic Functions (V36 or Greater) 

IEEESPAbs() FLOAT ( FLOAT parm ) ; 

Take absolute value of IEEE single-precision variable. 

IEEESPAdd() FLOAT IEEESPAdd( FLOAT leftParm, FLOAT rightParm); 
Add two IEEE single-precision variables. 

IEEESPCeil() FLOAT IEEESPCeil ( FLOAT parm ) ; 

Compute least integer greater than or equal to variable. 

IEEESPCmp() LONG IEEESPCmp ( FLOAT leftParm, FLOAT rightParm ); 
Compare two IEEE single-precision variables. 

IEEESPDiv() FLOAT IEEESPDiv( FLOAT dividend, FLOAT divisor ); 
Divide two IEEE single-precision variables. 

IEEESPFix() LONG IEEESPFix ( FLOAT parm ) ; 

Convert IEEE single-precision variable to integer. 

IEEESPFIoor() FLOAT lEEESPFloor ( FLOAT parm ) ; 

Compute largest integer less than or equal to variable. 



IEEESPFIt() FLOAT IEEESPFlt ( long integer ) ; 
Convert integer variable to IEEE single-precision. 

IEEESPMul() FLOAT IEEESPMul ( FLOAT lef tParm, FLOAT rightParm ) ; 
Multiply two IEEE single-precision variables. 

IEEESPNeg() FLOAT lEEESPNeg ( FLOAT parm ) ; 

Take two's complement of IEEE single-precision variable. 

IEEESPSub() FLOAT IEEESPSub( FLOAT leftParm, FLOAT rightParm ); 
Subtract two IEEE single-precision variables. 

IEEESPTSt() LONG IEEESPTst ( FLOAT parm ) ; 

Test an IEEE single-precision variable against zero. 
Be sure to include proper data type definitions, as shown in the example below. 

#include <exec/types .h> 

# include <libraries/mathieeesp.h> 

#include <clib/mathsingbas_protos . h> 

struct Library *MathIeeeSingBasBase; 

VOID main() 

{ 

FLOAT fl, f2, f3; 

LONG i 1 ; 

if (MathleeeSingBasBase = OpenLibrary ( "mathieeesingbas . library" , 37) ) 

{ 

il = IEEESPFix(f 1) ; 
f i = IEEESPFlt (il) ; 
switch (IEEESPCmp(f 1, f2)) 
switch (IEEESPTst (fl) ) { } ; 
f 1 = IEEESPAbs (f2) ; 
f 1 = lEEESPNeg (f 2) ; 



{}; 



/* 


Call 


IEEESPFix 


entry 


*/ 


/* 


Call 


IEEESPFlt 


entry 


*/ 


/* 


Call 


IEEESPCmp 


entry 


*/ 


/* 


Call 


IEEESPTst 


entry 


*/ 


/* 


Call 


IEEESPAbs 


entry 


*/ 


/* 


Call 


lEEESPNeg 


entry 


*/ 
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fl = IEEESPAdd(f2, f3) 

fl = IEEESPSub(f2, f3) 

fl = IEEESPMul (f2, f3) 

fl = IEEESPDiv(f2, f3) 

f 1 = IEEESPCeil (f2) ; 

fl = IEEESPFloor (f 2) ; 



/* Call IEEESPAdd entry */ 

/* Call IEEESPSub entry */ 

/* Call IEEESPMul entry */ 

/* Call IEEESPDiv entry */ 

/* Call IEEESPCeil entry */ 

/* Call IEEESPFloor entry */ 



CloseLibrary (MathleeeSingBasBase) 
} 



else 



} 



printf ( "Can' t open mathieeesingbas . library\n" ) 



The Amiga assembly language interface to the IEEE single-precision basic math routines is shown below, 
including some details about how the system flags are affected by each operation. Note that the access 
mechanism from assembly language is as shown below: 

MOVEA.L _MathIeeeSingBasBase,A6 
JSR LVOIEEESPFix(A6) 



Function 



SP IEEE Basic Assembly Functions 
Input Output 



Condition Codes 



_LVOIEEESPFix | D0=IEEE arg 



DO=Integer 



N=undef ined 





double -precis ion 


(two's complement) 


Z=undef ined 
V=undef ined 
C=undef ined 
X=undef ined 


LVOIEEESPFlt 


DO=Integer arg 


D0=IEEE 


N=undef ined 




(two' s 


single -precis ion 


Z=undef ined 




complement) 




V=undef ined 
C=undef ined 
X=undef ined 


_LVOIEEESPCmp 


D0=IEEE argl 


D0=+1 if argl>arg2 


N=l if result 




single -precis ion 


D0=-1 if argl<arg2 


is negative 




D1=IEEE arg2 


D0=0 if argl=arg2 


Z=l if result 




single -precis ion 




is zero 

v=o 

C=undef ined 
X=undef ined 
GT=arg2>argl 
GE=arg2 >=argl 
EQ=arg2=argl 
NE=arg2oargl 
LT=arg2<argl 
E= arg2<=argl 


LVOIEEESPTst 


D0=IEEE arg 


D0=+1 if arg>0.0 


N=l if result 




single -precis ion 


D0=-1 if arg<0.0 


is negative 






D0=0 if arg=0.0 


Z=l if result 
is zero 

v=o 

C=undef ined 
X=undef ined 
EQ=arg=0 . 
NE=arg<>0 . 
PL=arg>=0 . 
MI=arg<0 . 
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Function 



SP IEEE Basic Assembly Functions 
Input Output 



Condition Codes 



LVOIEEESPAbs 


D0=IEEE arg 


D0=IEEE 


N=undef ined 




single -precis ion 


single -precis ion 


Z=undef ined 






absolute value 


V=undef ined 
C=undef ined 
X=undef ined 


_LVOIEEESPNeg 


D0=IEEE arg 


D0=IEEE 


N=undef ined 




single -precis ion 


single -precis ion 


Z=undef ined 






negated 


V=undef ined 
C=undef ined 
X=undef ined 


LVOIEEESPAdd 


D0=IEEE argl 


D0=IEEE 


N=undef ined 




single -precis ion 


single -precis ion 


Z=undef ined 




D1=IEEE arg2 


addition of 


V=undef ined 




single -precis ion 


argl+arg2 


C=undef ined 
X=undef ined 


_LVOIEEESPSub 


D0=IEEE argl 


D0=IEEE 


N=undef ined 





single -precis ion 


single -precis ion 


Z=undef ined 




D1=IEEE arg2 


subtraction of 


V=undef ined 




single -precis ion 


argl-arg2 


C=undef ined 
X=undef ined 


LVOIEEESPMul 


D0=IEEE argl 


D0=IEEE 


N=undef ined 




single -precis ion 


single -precis ion 


Z=undef ined 




D1=IEEE arg2 


multiplication of 


V=undef ined 




single -precis ion 


argl*arg2 


C=undef ined 
X=undef ined 


LVOIEEESPDiv 


D0=IEEE argl 


D0=IEEE 


N=undef ined 




single -precis ion 


single -precis ion 


Z=undef ined 




D1=IEEE arg2 


division of 


V=undef ined 




single -precis ion 


argl/arg2 


C=undef ined 
X=undef ined 


LVOIEEESPCeil 


D0=IEEE variable 


D0=least integer 


N=undef ined 




single -precis ion 


>= variable 


Z=undef ined 
V=undef ined 
C=undef ined 
X=undef ined 


LVOIEEESPFloor 


D0=IEEE variable 


DO=largest integer 


N=undef ined 




single -precis ion 


<= arg 


Z=undef ined 
V=undef ined 
C=undef ined 
X=undef ined 
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IEEE Single-Precision Transcendental Math 
Library 

The IEEE single-precision transcendental math library was introduced in V36. It contains entries for 
transcendental math functions such as sine, cosine, and square root. 

This library resides on disk and is opened by calling OpenLibraryQ with "mathieeesingtrans. library" as the 
argument. Do not share the library base pointer between tasks -- see note at beginning of chapter. 

#include <exec/types . h> 

# include <libraries/mathieeesp.h> 

struct Library *MathIeeeSingTransBase; 

#include <clib/mathsingtrans_protos . h> 

VOID main() 

{ 

if (MathleeeSingTransBase = OpenLibrary ( "mathieeesingtrans . library" , 37) ) 

{ 



CloseLibrary (MathleeeSingTransBase) ; 

} 
else 

printf ( "Can' t open mathieeesingtrans . library\n" ) ; 
} 

The global variable MathleeeSingTransBase is used internally for all future library references. 

The IEEE single-precision transcendental math library is dependent upon the IEEE single-precision basic math 
library, which it will open if it is not open already. If you want to use the IEEE single-precision basic math 



functions in conjunction with the transcendental math functions however, you have to specifically open the basic 
math library yourself. 

Just as the IEEE single-precision basic math library, the IEEE single-precision transcendental math library will 
take advantage of a 680X0/68881 combination or another math resource, if present. 

SP IEEE Transcendental Functions (V36 Or Greater) 

IEEESPAsin() FLOAT lEEESPAsin ( FLOAT parm ) ; 
Return arcsine of IEEE single-precision variable. 

IEEESPAC0S() FLOAT IEEESPACOS ( FLOAT parm ) ; 

Return arccosine of IEEE single-precision variable. 

IEEESPAtan() FLOAT lEEESPAtan( FLOAT parm ) ; 

Return arctangent of IEEE single-precision variable. 

IEEESPSin() FLOAT lEEESPSin( FLOAT parm ); 

Return sine of IEEE single-precision variable. This function accepts an IEEE radian argument and 
returns the trigonometric sine value. 

IEEESPC0S() FLOAT IEEESPCOS ( FLOAT parm ) ; 

Return cosine of IEEE single-precision variable. This function accepts an IEEE radian argument and 
returns the trigonometric cosine value. 
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IEEESPTan() FLOAT IEEESPTan( FLOAT parm ) ; 

Return tangent of IEEE single-precision variable. This function accepts an IEEE radian argument and 
returns the trigonometric tangent value. 

IEEESPSinCOS() FLOAT IEEESPSincos ( FLOAT *cosptr, FLOAT parm ) ; 

Return sine and cosine of IEEE single-precision variable. This function accepts an IEEE radian 
argument and returns the trigonometric sine as its result and the cosine in the first parameter. 

IEEESPSinh() FLOAT IEEESPSinh( FLOAT parm ) ; 

Return hyperbolic sine of IEEE single-precision variable. 

IEEESPC0Sh() FLOAT IEEESPCosh ( FLOAT parm ) ; 

Return hyperbolic cosine of IEEE single-precision variable. 

IEEESPTanh() FLOAT IEEESPTanh( FLOAT parm ) ; 

Return hyperbolic tangent of IEEE single-precision variable. 

IEEESPExp() FLOAT IEEESPExp( FLOAT parm ) ; 

Return e to the IEEE variable power. This function accept an IEEE single-precision argument and 
returns the result representing the value of e (2.712828...) raised to that power. 

IEEESPFieee() FLOAT IEEESPFieee ( FLOAT parm ) ; 

Convert IEEE single-precision number to IEEE single-precision number. The only purpose of this 
function is to provide consistency with the double-precision math IEEE library. 

IEEESPLog() FLOAT IEEESPLog ( FLOAT parm ) ; 

Return natural log (base e of IEEE single-precision variable. 

IEEESPLog10() FLOAT IEEESPLoglO ( FLOAT parm ) ; 

Return log (base 10) of IEEE single-precision variable. 

IEEESPPow() FLOAT IEEESPPow( FLOAT exp, FLOAT arg ); 

Return IEEE single-precision arg2 to IEEE single-precision argl . 

IEEESPSqrt() FLOAT IEEESPSqrt ( FLOAT parm ) ; 

Return square root of IEEE single-precision variable. 



IEEESPTieee() FLOAT lEEESPTieee ( FLOAT parm ) ; 

Convert IEEE single-precision number to IEEE single-precision number. The only purpose of this 
function is to provide consistency with the double-precision math IEEE library. 

Be sure to include the proper data type definitions as shown below. 

#include <exec/types .h> 

# include <libraries/mathieeesp.h> 

#include <clib/mathsingtrans_protos . h> 

struct Library *MathIeeeSingTransBase; 

VOID main() 

{ 

FLOAT fl, f2, f3; 

if (MathleeeSingTransBase = OpenLibrary ( "mathieeesingtrans . library" , 37) ) 



{ 

fl 
fl 
fl 
fl 
fl 



IEEEDPAsin(f2) 
IEEEDPAcos (f2) 
IEEEDPAtan(f2) 
IEEEDPSin(f2) ; 
IEEEDPCos (f2) ; 



/* Call IEEESPAsin entry */ 

/* Call IEEESPAcos entry */ 

/* Call IEEESPAtan entry */ 

/* Call IEEESPSin entry */ 

/* Call IEEESPCos entry */ 
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f 1 = IEEEDPTan(f2) ; 

fl = IEEEDPSincos (&f3, 

fl = IEEEDPSinh(f2) 

fl = IEEEDPCosh(f2) 

fl = IEEEDPTanh(f2) 

f 1 = IEEEDPExp(f2) ; 

f 1 = IEEEDPLog(f2) ; 

fl = IEEEDPLoglO (f2) ; 

fl = IEEEDPPow(d2, f3) 

f 1 = IEEEDPSqrt (f2) ; 



f2) 



/* Call 

/* Call 

/* Call 

/* Call 

/* Call 

/* Call 

/* Call 

/* Call 

/* Call 

/* Call 



IEEESPTan entry */ 
IEEESPSincos entry */ 
IEEESPSinh entry */ 
IEEESPCosh entry */ 
IEEESPTanh entry */ 
IEEESPExp entry */ 
IEEESPLog entry */ 
IEEESPLoglO entry */ 
IEEESPPow entry */ 
IEEESPSqrt entry */ 



CloseLibrary (MathleeeSingTransBase) ; 

} 
else printf ( "Can' t open mathieeesingtrans . library\n" ) ; 

} 

The section below describes the Amiga assembly interface to the IEEE single-precision transcendental math 
library. The access mechanism from assembly language is: 

MOVEA . L _MathIeeeSingTransBase , A6 
JSR LVOIEEESPAsin(A6) 



Function 



SP IEEE Transcendental Assembly Functions 

Input Output Condition Codes 



LVOIEEESPAsin 


D0=IEEE arg 


D0=IEEE arcsine 


N=undef ined 






radian 


Z=undef ined 
V=undef ined 
C=undef ined 
X=undef ined 


LVOIEEESPACOS 


D0=IEEE arg 


D0=IEEE arccosine 


N=undef ined 




single -precis ion 


radian 


Z=undef ined 
V=undef ined 
C=undef ined 
X=undef ined 


LVOIEEESPAtan 


D0=IEEE arg 


D0=IEEE arctangent 


N=undef ined 





single -precis ion 


radian 


Z=undef ined 
V=undef ined 
C=undef ined 
X=undef ined 


LVOIEEESPSin 


D0=IEEE arg 


D0=IEEE sine 


N=undef ined 




in radians 




Z=undef ined 




single -precis ion 




V=undef ined 
C=undef ined 
X=undef ined 


LVOIEEESPCos 


D0=IEEE arg 


D0=IEEE cosine 


N=undef ined 




in radians 




Z=undef ined 




single -precis ion 




V=undef ined 
C=undef ined 
X=undef ined 


LVOIEEESPTan 


D0=IEEE arg 


D0=IEEE tangent 


N=undef ined 




in radians 




Z=undef ined 




single -precis ion 




V=undef ined 
C=undef ined 
X=undef ined 
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Function 



SP IEEE Transcendental Assembly Functions 

Input Output Condition Codes 



LVOIEEESPSincos 


A0=Addr to store 


D0=IEEE sine 


N=undef ined 




cosine result 


(A0)=IEEE cosine 


Z=undef ined 




D0=IEEE arg 




V=undef ined 




in radians 




C=undef ined 
X=undef ined 


LVOIEEESPSinh 


D0=IEEE arg 


D0=IEEE hyperbolic 


N=undef ined 




in radians 


sine 


Z=undef ined 




single -precis ion 




V=undef ined 
C=undef ined 
X=undef ined 


LVOIEEESPCosh 


D0=IEEE arg 


D0=IEEE hyperbolic 


N=undef ined 




in radians 


cosine 


Z=undef ined 




single -precis ion 




V=undef ined 
C=undef ined 
X=undef ined 


LVOIEEESPTanh 


D0=IEEE arg 


D0=IEEE hyperbolic 


N=undef ined 




in radians 


tangent 


Z=undef ined 




single -precis ion 




V=undef ined 
C=undef ined 
X=undef ined 


_LVOIEEESPExp 


D0=IEEE arg 


D0=IEEE exponential 


N=undef ined 




single -precis ion 




Z=undef ined 
V=undef ined 
C=undef ined 
X=undef ined 


LVOIEEESPLog 


D0=IEEE arg 


D0=IEEE natural 


N=undef ined 




single -precis ion 


logarithm 


Z=undef ined 
V=undef ined 











C=undef ined 










X=undef ined 


LVOIEEESPLoglO 


D0=IEEE arg 


D0 = 


=IEEE logarithm 


N=undef ined 




single -precis ion 




(base 10) 


Z=undef ined 
V=undef ined 
C=undef ined 
X=undef ined 


LVOIEEESPPow 


D0=IEEE 


D0 = 


=IEEE result of 


N=undef ined 




exponent value 




arg taken to 


Z=undef ined 




single -precis ion 




exp power 


V=undef ined 




D1=IEEE 






C=undef ined 




arg value 






X=undef ined 




single -precis ion 








_LVOIEEESPSqrt 


D0=IEEE arg 
single -precis ion 


D0 = 


=IEEE square root 


N=undef ined 
Z=undef ined 
V=undef ined 
C=undef ined 
X=undef ined 
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IEEE Double-Precision Data Format 



The IEEE double-precision variables are defined as 64-bit entities with the following format: 



SEEEEEEE 
63 


EEEEEIMM 
55 


MMMMMMMM 

47 


MMMMMMMM 
39 




MMMMMMMM 
31 


MMMMMMMM 
23 


MMMMMMMM 
15 


MMMMMMMM 
7 



Hidden Bit In The Mantissa. There is a "hidden" bit in the mantissa part of the IEEE numbers. 
Since all numbers are normalized, the integer (high) bit of the mantissa is dropped off. The 
IEEE double-precision range is 2.2E-308 (4.9E-324 de-normalized) to 1.8E+307. 

The exponent is the power of two needed to correctly position the mantissa to reflect the number's true arithmetic 
value. If both the exponent and the mantissa have zero in every position, the value is zero. If only the exponent 
has zero in every position, the value is an unnormal (extremely small). If all bits of the exponent are set to 1 the 
value is either a positive or negative infinity or a Not a Number (NaN). NaN is sometimes used to indicate an 
uninitialized variable. 

IEEE Double-Precision Basic Math Library 

The IEEE double-precision basic math library contains entries for the basic IEEE mathematics functions, such as 
add, subtract, and divide. This library resides on disk and is opened by calling OpenLibraryQ with 
"mathieeedoubbas. library" as the argument. Do not share the library base pointer between tasks - see note at 
beginning of chapter for details. 



#include <exec/types . h> 

# include <libraries/mathieeedp.h> 

#include <clib/mathdoubbas_protos . h> 

struct Library *MathIeeeDoubBasBase; 



VOID main() 

{ 

/* do not share base pointer between tasks. */ 
if (MathleeeDoubBasBase = OpenLibrary ( "mathieeedoubbas . library" , 34)) 

{ 

CloseLibrary (MathleeeDoubBasBase) ; 

} 
else printf ( "Can' t open mathieeedoubbas . library\n" ) ; 

} 

The global variable MathleeeDoubBasBase is used internally for all future library references. 

If an 680X0/68881/68882 processor combination is available, it will be used by the IEEE basic library instead of 
the software emulation. Also, if an autoconfigured math resource is available, that will be used. Typically this is a 
68881 designed as a 16 bit I/O port, but it could be another device as well. 
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DP IEEE Basic Functions 

IEEEDPAbS() DOUBLE IEEEDPAbs ( DOUBLE parm ) ; 

Take absolute value of IEEE double-precision variable. 

IEEEDPAdd() DOUBLE IEEEDPAdd( DOUBLE leftParm, DOUBLE rightParm ); 

Add two IEEE double-precision variables. 

IEEEDPCeM() DOUBLE IEEEDPCeil ( DOUBLE parm ) ; 

Compute least integer greater than or equal to variable. 

IEEEDPCmp() LONG IEEEDPCmp ( DOUBLE leftParm, DOUBLE rightParm ); 
Compare two IEEE double-precision variables. 

IEEEDPDiv() DOUBLE IEEEDPDiv( DOUBLE dividend, DOUBLE divisor ) ; 

Divide two IEEE double-precision variables. 

IEEEDPFix() LONG IEEEDPFix ( DOUBLE parm ) ; 

Convert IEEE double-precision variable to integer. 

IEEEDPFIoor() DOUBLE IEEEDPFloor ( DOUBLE parm ) ; 

Compute largest integer less than or equal to variable. 

IEEEDPFIt() DOUBLE IEEEDPFlt ( long integer ) ; 
Convert integer variable to IEEE double-precision. 

IEEEDPMul() DOUBLE IEEEDPMul ( DOUBLE factorl, DOUBLE factor2 ); 

Multiply two IEEE double-precision variables. 

IEEEDPNeg() DOUBLE lEEEDPNeg ( DOUBLE parm ) ; 

Take two's complement of IEEE double-precision variable. 

IEEEDPSub() DOUBLE IEEEDPSub( DOUBLE leftParm, DOUBLE rightParm ) ; 

Subtract two IEEE double-precision variables. 

IEEEDPTSt() LONG IEEEDPTst ( DOUBLE parm ) ; 

Test an IEEE double-precision variable against zero. 
Be sure to include proper data type definitions, as shown in the example below. 

#include <exec/types . h> 

# include <libraries/mathieeedp.h> 

#include <clib/mathieeedoubbas_protos . h> 

struct Library *MathIeeeDoubBasBase; 



VOID main() 

{ 

DOUBLE dl , d2 , d3 ; 

LONG i 1 ; 

if (MathleeeDoubBasBase = OpenLibrary ( "mathieeedoubbas . library" , 34) ) 
{ 



il = IEEEDPFix(dl) ; 

f i = IEEEDPFlt (il) ; 

switch (IEEEDPCmp(dl, d2 ) ) { } ; 

switch (IEEEDPTst (dl) ) { } ; 

dl = IEEEDPAbs (d2) ; 

dl = IEEEDPNeg(d2) ; 

dl = IEEEDPAdd(d2, d3 ) ; 

dl = IEEEDPSub(d2, d3 ) ; 



/* 


Call 


IEEEDPFix 


entry 


*/ 


/* 


Call 


IEEEDPFlt 


entry 


*/ 


/* 


Call 


IEEEDPCmp 


entry 


*/ 


/* 


Call 


IEEEDPTst 


entry 


*/ 


/* 


Call 


IEEEDPAbs 


entry 


*/ 


/* 


Call 


IEEEDPNeg 


entry 


*/ 


/* 


Call 


IEEEDPAdd 


entry 


*/ 


/* 


Call 


IEEEDPSub 


entry 


*/ 
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dl = IEEEDPMul (d2, d3 ) ; 
dl = IEEEDPDiv(d2, d3 ) ; 
dl = IEEEDPCeil (d2) ; 
dl = IEEEDPFloor (d2) ; 

CloseLibrary (MathleeeDoubBasBase) ; 



/* Call IEEEDPMul entry */ 

/* Call IEEEDPDiv entry */ 

/* Call IEEEDPCeil entry */ 

/* Call IEEEDPFloor entry */ 



else printf ( "Can' t open mathieeedoubbas . library\n" ) ; 
} 

The Amiga assembly language interface to the IEEE double-precision floating-point basic math routines is shown 
below, including some details about how the system flags are affected by each operation. The access 
mechanism from assembly language is: 

MOVEA.L _MathIeeeDoubBasBase,A6 
JSR LV0IEEEDPFix(A6) 



Function 



DP IEEE Basic Assembly Functions 
Input Output 



Condition Codes 



LVOIEEEDPFix 


D0/D1=IEEE arg 


DO=Integer 


N=undef ined 




double -precis ion 


(two's complement) 


Z=undef ined 
V=undef ined 
C=undef ined 
X=undef ined 


LVOIEEEDPF1 


DO=Integer arg 


D0/D1=IEEE 


N=undef ined 




(two' s 


double -precis ion 


Z=undef ined 




complement) 




V=undef ined 
C=undef ined 
X=undef ined 


_LVOIEEEDPCmp 


D0/D1=IEEE argl 


D0=+1 if argl>arg2 


N=l if result 




double -precis ion 


D0=-1 if argl<arg2 


is negative 




D2/D3=IEEE arg2 


D0=0 if argl=arg2 


Z=l if result 




double -precis ion 




is zero 

v=o 

C=undef ined 

X=undef ined 

GT=arg2>argl 

GE=arg2>=argl 

EQ=arg2=argl 

NE=arg2oargl 

LT=arg2<argl 



LE=arg2<=argl 



LVOIEEEDPTst 



D0/D1=IEEE arg 
double -precis ion 



D0=+1 if arg>0.0 
D0=-1 if arg<0.0 
D0=0 if arg=0.0 



N=l if result 

is negative 

Z=l if result 

is zero 
V=0 

C=undef ined 
X=undef ined 
EQ=arg=0 . 
NE=arg<>0 . 
PL=arg>=0 . 
MI=arg<0 . 
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DP IEEE Basic Assembly Functions 



Function 



Input 



Output 



Condition Codes 



LVOIEEEDPAbs 


D0/D1=IEEE arg 


D0/D1=IEEE 


N=undef ined 




double -precis ion 


double -precis ion 


Z=undef ined 






absolute value 


V=undef ined 
C=undef ined 
X=undef ined 


_LVOIEEEDPNeg 


D0/D1=IEEE arg 


D0/D1=IEEE 


N=undef ined 




double -precis ion 


double -precis ion 


Z=undef ined 






negated 


V=undef ined 
C=undef ined 
X=undef ined 


LVOIEEEDPAdd 


D0/D1=IEEE argl 


D0/D1=IEEE 


N=undef ined 




double -precis ion 


double -precis ion 


Z=undef ined 






addition of 


V=undef ined 




D2/D3=IEEE arg2 


argl+arg2 


C=undef ined 




double -precis ion 




X=undef ined 


LVOIEEEDPSub 


D0/D1=IEEE argl 


D0/D1=IEEE 


N=undef ined 




double -precis ion 


double -precis ion 


Z=undef ined 






subtraction of 


V=undef ined 




D2/D3=IEEE arg2 


argl-arg2 


C=undef ined 




double -precis ion 




X=undef ined 


LVOIEEEDPMul 


D0/D1=IEEE argl 


D0/D1=IEEE 


N=undef ined 




double -precis ion 


double -precis ion 


Z=undef ined 






multiplication of 


V=undef ined 




D2/D3=IEEE arg2 


argl*arg2 


C=undef ined 




double -precis ion 




X=undef ined 


LVOIEEEDPDiv 


D0/D1=IEEE argl 


D0/D1=IEEE 


N=undef ined 




double -precis ion 


double -precis ion 


Z=undef ined 






division of 


V=undef ined 




D2/D3=IEEE arg2 


argl/arg2 


C=undef ined 




double -precis ion 




X=undef ined 


LVOIEEEDPCeil 


D0/D1=IEEE arg 


DO/Dl=least 


N=undef ined 




double -precis ion 


integer 


Z=undef ined 






>= arg 


V=undef ined 
C=undef ined 
X=undef ined 











LVOIEEEDPFloor 


D0/D1=IEEE arg 


DO/Dl=largest 


N=undef ined 




double -precis ion 


integer 


Z=undef ined 






<= arg 


V=undef ined 
C=undef ined 
X=undef ined 
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IEEE Double-Precision Transcendental Math 
Libraries 

The IEEE double-precision transcendental math library contains entries for the transcendental math functions 
such as sine, cosine, and square root. The library resides on disk and is opened by calling OpenLibrary() with 
"mathieeedoubtrans. library" as the argument. Do not share the library base pointer between tasks -- see note at 
beginning of chapter for details. 

#include <exec/types . h> 

# include <libraries/mathieeedp.h> 

#include <clib/mathdoubtrans jprotos . h> 

struct Library *MathIeeeDoubTransBase; 

VOID main() 

{ 

if (MathleeeDoubTransBase = OpenLibrary ( "mathieeedoubtrans . library" , 34) ) 

{ 

CloseLibrary (MathleeeDoubTransBase) ; 

} 
else printf ( "Can' t open mathieeedoubtrans . library\n" ) ; 

} 

The global variable MathleeeDoubTransBase is used internally for all future library references. 

The IEEE double-precision transcendental math library is dependent upon the IEEE double-precision basic math 
library, which it will open if it is not open already. If you want to use the IEEE double-precision basic math 
functions in conjunction with the transcendental math functions however, you have to specifically open the basic 
math library yourself. 

Just as the IEEE double-precision basic math library, the IEEE double-precision transcendental math library will 
take advantage of a 680X0/68881 combination or another math resource, if present. 

DP IEEE Transcendental Functions 

IEEEDPAsin() DOUBLE IEEEDPAsin( DOUBLE parm ) ; 
Return arcsine of IEEE variable. 

IEEEDPAC0S() DOUBLE IEEEDPACOS ( DOUBLE parm ) ; 

Return arccosine of IEEE variable. 



IEEEDPAtan() DOUBLE IEEEDPAtan ( DOUBLE parm ) ; 
Return arctangent of IEEE variable. 

IEEEDPSin() DOUBLE IEEEDPSinf DOUBLE parm ); 

Return sine of IEEE variable. This function accepts an IEEE radian argument and returns the 
trigonometric sine value. 

IEEEDPC0S() DOUBLE IEEEDPCOS ( DOUBLE parm ) ; 

Return cosine of IEEE variable. This function accepts an IEEE radian argument and returns the 



trigonometric cosine value. 
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IEEEDPTan() DOUBLE lEEEDPTan ( DOUBLE parm ) ; 

Return tangent of IEEE variable. This function accepts an IEEE radian argument and returns the 
trigonometric tangent value. 

IEEEDPSinCOS() DOUBLE IEEEDPSincos ( DOUBLE *pf 2 , DOUBLE parm ) ; 

Return sine and cosine of IEEE variable. This function accepts an IEEE radian argument and returns 
the trigonometric sine as its result and the trigonometric cosine in the first parameter. 

IEEEDPSinh() DOUBLE IEEEDPSinh( DOUBLE parm ); 
Return hyperbolic sine of IEEE variable. 

IEEEDPCosh() DOUBLE IEEEDPCosh( DOUBLE parm ); 
Return hyperbolic cosine of IEEE variable. 

IEEEDPTanh() DOUBLE IEEEDPTanh( DOUBLE parm ); 
Return hyperbolic tangent of IEEE variable. 

IEEEDPExp() DOUBLE IEEEDPExp ( DOUBLE parm ) ; 

Return e to the IEEE variable power. This function accept an IEEE argument and returns the result 
representing the value of e (2.712828...) raised to that power. 

IEEEDPFieee() DOUBLE IEEEDPFieee( FLOAT single ) ; 

Convert IEEE single-precision number to IEEE double-precision number. 

IEEEDPLog() DOUBLE IEEEDPLog ( DOUBLE parm ) ; 

Return natural log (base e of IEEE variable. 

IEEEDPLog10() DOUBLE IEEEDPLoglO( DOUBLE parm ); 

Return log (base 10) of IEEE variable. 

IEEEDPPOW() DOUBLE IEEEDPPow( DOUBLE exp, DOUBLE arg ) ; 

Return IEEE arg2 to IEEE argl . 

IEEEDPSqrt() DOUBLE IEEEDPSqrt ( DOUBLE parm ) ; 
Return square root of IEEE variable. 

IEEEDPTieee() FLOAT IEEEDPTieee ( DOUBLE parm ) ; 

Convert IEEE double-precision number to IEEE single-precision number. 

Be sure to include proper data type definitions as shown below. 

#include <exec/types .h> 

# include <libraries/mathieeedp.h> 

#include <clib/mathdoubtrans_protos . h> 

struct Library *MathIeeeDoubTransBase; 

VOID mainO 

{ 

DOUBLE dl , d2 , d3 ; 

FLOAT fl; 



if (MathleeeDoubTransBase = OpenLibrary ( "mathieeedoubtrans . library" , 34) ) 

{ 

/* Call IEEEDPAsin entry */ 

/* Call IEEEDPAcos entry */ 

/* Call IEEEDPAtan entry */ 

/* Call IEEEDPSin entry */ 

/* Call IEEEDPCos entry */ 

/* Call lEEEDPTan entry */ 



dl = IEEEDPAsin (d2) 
dl = IEEEDPAcos (d2) 
dl = IEEEDPAtan (d2) 
dl = IEEEDPSin (d2) 
dl = IEEEDPCos (d2) 
dl = lEEEDPTan (d2) 



dl = IEEEDPSincos (&d3, d2 ) ; /* Call IEEEDPSincos entry */ 
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dl = IEEEDPSinh(d2) ; /* Call 

dl = IEEEDPCosh(d2) ; /* Call 

dl = IEEEDPTanh(d2) ; /* Call 

dl = IEEEDPExp(d2) ; /* Call 

dl = IEEEDPLog(d2) ; /* Call 

dl = IEEEDPLoglO (d2) ; /* Call 

dl = IEEEDPPow(d2, d3 ) ; /* Call 

dl = IEEEDPSqrt (d2) ; /* Call 

fl = IEEEDPTieee (d2) ; /* Call 

dl = IEEEDPFieee (f 1) ; /* Call 



IEEEDPSinh entry */ 
IEEEDPCosh entry */ 
IEEEDPTanh entry */ 
IEEEDPExp entry */ 
IEEEDPLog entry */ 
IEEEDPLoglO entry */ 
IEEEDPPow entry */ 
IEEEDPSqrt entry */ 
IEEEDPTieee entry */ 
IEEEDPFieee entry */ 



CloseLibrary (MathleeeDoubTransBase) ; 

} 
else printf ( "Can' t open mathieeedoubtrans . library\n" ) ; 

} 

The section below describes the Amiga assembly interface to the IEEE double-precision transcendental math 
library. The access mechanism from assembly language is: 

MOVEA . L _MathIeeeDoubTransBase , A6 
JSR LVOIEEEDPAsin(A6) 



Function 



DP IEEE Transcendental Assembly Functions 

Input Output Condition Codes 



_LVOIEEEDPAsin D0/D1=IEEE arg D0/D1=IEEE N=undefined 

| arcsine radian | Z=undefined 

| V=undefined 
1 | C=undefined 

| X=undefined 


_LVOIEEEDPAcos D0/D1=IEEE arg D0/D1=IEEE N=undefined 

| arccosine radian | Z=undefined 

| V=undefined 
| C=undefined 
| X=undefined 


_LVOIEEEDPAtan D0/D1=IEEE arg D0/D1=IEEE N=undefined 

| arctangent radian | Z=undefined 

| V=undefined 
i | C=undefined 

| X=undefined 


_LVOIEEEDPSin j D0/D1=IEEE arg D0/D1=IEEE sine N=undefined 

in radians | Z=undefined 
i | V=undefined 

| C=undefined 
1 | X=undefined 


_LVOIEEEDPCos D0/D1=IEEE arg D0/D1=IEEE cosine N=undefined 

in radians | Z=undefined 
j | V=undefined 
1 | C=undefined 
i | X=undefined 


_LVOIEEEDPTan D0/D1=IEEE arg D0/D1=IEEE tangent N=undefined 

in radians i | Z=undefined 

| V=undefined 
l | C=undefined 
! | X=undefined 
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DP IEEE Transcendental Assembly Functions 



Function 



Input 



Output 



Condition Codes 



LVOIEEEDPSincos 


AO=Address to 


D0/D1=IEEE sine 


N=undef ined 




store cosine 


(AO) =IEEE cosine 


Z=undef ined 




result 




V=undef ined 




D0/D1=IEEE arg 




C=undef ined 




in radians 




X=undef ined 


LVOIEEEDPSin 


D0/D1=IEEE arg 


D0/D1=IEEE 


N=undef ined 




in radians 


hyperbolic sine 


Z=undef ined 
V=undef ined 
C=undef ined 
X=undef ined 


LVOIEEEDPCosh 


D0/D1=IEEE arg 


D0/D1=IEEE 


N=undef ined 




in radians 


hyperbolic cosine 


Z=undef ined 
V=undef ined 
C=undef ined 
X=undef ined 


LVOIEEEDPTanh 


D0/D1=IEEE arg 


D0/D1=IEEE 


N=undef ined 




in radians 


hyperbolic tangent 


Z=undef ined 
V=undef ined 
C=undef ined 
X=undef ined 


_LVOIEEEDPExp 


D0/D1=IEEE arg 


D0/D1=IEEE 


N=undef ined 






exponential 


Z=undef ined 
V=undef ined 
C=undef ined 
X=undef ined 


LVOIEEEDPLog 


D0/D1=IEEE arg 


D0/D1=IEEE natural 


N=undef ined 






logarithm 


Z=undef ined 
V=undef ined 
C=undef ined 
X=undef ined 


LVOIEEEDPLoglO 


D0/D1=IEEE arg 


D0/D1=IEEE 


N=undef ined 






logarithm 


Z=undef ined 






(base 10) 


V=undef ined 
C=undef ined 
X=undef ined 


LVOIEEEDPPow 


D0/D1=IEEE exp 


D0/D1=IEEE 


N=undef ined 




D2/D3=IEEE arg 


of arg taken to 


Z=undef ined 






exp power 


V=undef ined 
C=undef ined 
X=undef ined 


_LVOIEEEDPSqrt 


D0/D1=IEEE arg 


D0/D1=IEEE 


N=undef ined 






square root 


Z=undef ined 
V=undef ined 
C=undef ined 
X=undef ined 
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DP IEEE Transcendental Assembly Functions 



Function 



Input 



Output 



Condition Codes 



LVOIEEEDPTieee 



D0/D1=IEEE arg 



DO = single -precis ion 
IEEE floating-point 
format 



N=undef ined 
Z=undef ined 
V=undef ined 
C=undef ined 
X=undef ined 



Function Reference 



Here's a brief summary of the functions covered in this chapter. Refer to the Amiga ROM Kernel Reference 
Manual: Includes and Autodocs for additional information. 



FFP Basic Functions 


SPAbS() 


i aKe aDsoiuie vaiue or i-i-k vanaDie 


SPAdd() 


Add two FFP variables 


SPCeil() 


Compute least integer greater than or equal to variable. 


SPCmp() 


Compare two FFP variables 


SPDiv() 


Divide two FFP variables 


SPFix() 


Convert FFP variable to integer 


SPFIoor() 


Computer largest integer less than or equal to variable. 


SPFIt() 


Convert integer variable to FFP 


SPMul() 


Multiply two FFP variables 


SPNeg() 


Take two's complement of FFP variable 


SPSub() 


Subtract two FFP variables 


SPTst() 


Test an FFP variable against zero 



FFP Transcendental Functions 


SPAcos() 


hieturn arccosme ot \-\-r variable. 


SPAsin() 


Return arcsine of FFP variable. 


SPAtan() 


Return arctangent of FFP variable. 


SPCos() 


Return cosine of FFP variable. 


SPCosh() 


Return hyperbolic cosine of FFP variable. 


SPExp() 


Return e to the FFP variable power. 


SPFieee() 


Convert IEEE variable to FFP format. 


SPLog() 


Return natural log (base e) of FFP variable. 


SPLog10() 


Return log (base 10) of FFP variable. 


SPPow() 


Return FFP arg2 to FFP argl . 


SPSin() 


Return sine of FFP variable. 


SPSincos() 


Return sine and cosine of FFP variable. 


SPSinh() 


Return hyperbolic sine of FFP variable. 


SPSqrt() 


Return square root of FFP variable. 


SPTan() 


Return tangent of FFP variable. 


SPTanh() 


Return hyperbolic tangent of FFP variable. 


SPTieee() 


Convert FFP variable to IEEE format 
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afp() 
fpa() 
arnd() 
dbf() 



Math Support Functions 



Convert ASCII string into FFP equivalent. 
Convert FFP variable into ASCII equivalent. 
Round ASCII representation of FFP number. 
Convert FFP dual-binary number to FFP equivalent. 



SP IEEE Basic Functions (V36) 

IEEESPAbs() I ake absolute value of Ibbb single-precision variable. 

IEEESPAdd() Add two IEEE single-precision variables. 

lEEESPCeilQ Compute least integer greater than or equal to variable. 

lEEESPCmpO Compare two IEEE single-precision variables. 

IEEESPDiv() Divide two IEEE single-precision variables. 

IEEESPFix() Convert IEEE single-precision variable to integer. 

IEEESPFIoor() Compute largest integer less than or equal to variable. 

IEEESPFIt() Convert integer variable to IEEE single-precision. 

IEEESPMul() Multiply two IEEE single-precision variables. 

IEEESPNeg() Take two's complement of IEEE single-precision variable. 

IEEESPSub() Subtract two IEEE single-precision variables. 

IEEESPTst() Test an IEEE single-precision variable against zero. 



SP IEEE Transcendental Functions (V36) 

Return arccosine of IEEE single-precision variable. 

Return arcsine of IEEE single-precision variable. 

Return arctangent of IEEE single-precision variable. 

Return cosine of IEEE single-precision variable. 

Return hyperbolic cosine of IEEE single-precision variable. 

Return e to the IEEE variable power. 

Return natural log (base e of IEEE single-precision variable. 

Return log (base 10) of IEEE single-precision variable. 

Return power of IEEE single-precision variable. 

Return sine of IEEE single-precision variable. 

Return sine and cosine of IEEE single-precision variable. 

Return hyperbolic sine of IEEE single-precision variable. 

Return square root of IEEE single-precision variable. 

Return tangent of IEEE single-precision variable. 

Return hyperbolic tangent of IEEE single-precision variable. 



l EEES P ACOSO 

IEEESPASin() 

IEEESPAtan() 

IEEESPCos() 

IEEESPCosh() 

IEEESPExp() 

IEEESPLog() 

IEEESPLog10() 

IEEESPPow() 

IEEESPSin() 

IEEESPSincos() 

IEEESPSinh() 

IEEESPSqrt() 

IEEESPTan() 

IEEESPTanh() 
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DP Ibbb basic hunctions 



lEEEDPAbs() Take absolute value of IEEE double-precision variable. 

IEEEDPAdd() Add two IEEE double-precision variables. 

IEEEDPCeil() Compute least integer greater than or equal to variable. 

lEEEDPCmpO Compare two IEEE double-precision variables. 

IEEEDPDiv() Divide two IEEE double-precision variables. 

IEEEDPFix() Convert IEEE double-precision variable to integer. 

IEEEDPFIoor() Compute largest integer less than or equal to variable. 

IEEEDPFIt() Convert integer variable to IEEE double-precision. 

IEEEDPMul() Multiply two IEEE double-precision variables. 

IEEEDPNeg() Take two's complement of IEEE double-precision variable. 

IEEEDPSub() Subtract two IEEE single-precision variables. 

IEEEDPTst() Test an IEEE double-precision variable against zero. 



IbbbUPACosO 

IEEEDPASin() 

IEEEDPAtan() 

IEEEDPCos() 

IEEEDPCosh() 

IEEEDPExp() 

IEEEDPFieee() 

IEEEDPLog() 

IEEEDPLog10() 

IEEEDPPow() 

IEEEDPSin() 

IEEEDPSincos() 

IEEEDPSinh() 

IEEEDPSqrt() 

IEEEDPTan() 

IEEEDPTanh() 

IEEEDPTieee() 



DP IEEE Transcendental Functions 

hieturn arccosme ot ibbb aouoie-precision vanaoie. 

Return arcsine of IEEE double-precision variable. 

Return arctangent of IEEE double-precision variable. 

Return cosine of IEEE double-precision variable. 

Return hyperbolic cosine of IEEE double-precision variable. 

Return e to the IEEE variable power. 

Convert IEEE single-precision number to IEEE double-precision number. 

Return natural log (base e of IEEE double-precision variable. 

Return log (base 10) of IEEE double-precision variable. 

Return power of IEEE double-precision variable. 

Return sine of IEEE double-precision variable. 

Return sine and cosine of IEEE double-precision variable. 

Return hyperbolic sine of IEEE double-precision variable. 

Return square root of IEEE double-precision variable. 

Return tangent of IEEE double-precision variable. 

Return hyperbolic tangent of IEEE double-precision variable. 

Convert IEEE double-precision number to IEEE single-precision number. 



Compile and Link Commands for SAS C 5.10 

FFP Basic, Transcendental and Math Support functions 

lc -bl -cfistq -ff -v -y <filename> . c 
blink lib:c.o + <filename>.o TO <filename> LIB lib: lcmf fp. lib + lib:lc.lib + lib:amiga. lib 

IEEE Single-Precision and Double-Precision Basic and Transcendental 
Functions 

lc -bl -cfistq -fi -v -y <filename> . c 
blink lib:c.o + <f ilename> . o TO <filename> LIB lib: lcmieee . lib + lib:lc.lib + lib:amiga. lib 
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Chapter 36 
Translator Device 



This chapter describes the translator library which, together with the narrator device, provides the Amiga's 
text-to-speech capability. To fully understand how speech is produced on the Amiga, you should also read the 
"Narrator Device" chapter of the Amiga ROM Kernel Reference Manual: Devices. 

The translator library provides a single function, Translate(), that converts an English language string into a 
phonetic string. You may then pass this phonetic string to the narrator device which will say the string using the 
Amiga's audio hardware. The two subsystems may also be used individually. You don't have to use the narrator 
to say the phonetic strings; you could use them instead for phonetic analysis or some other special purpose. 

Opening the Translator Library 

To use the TranslateQ function, you must first open the translator library. Setting a global variable, 
TranslatorBase, to the value returned from the call to OpenLibrary() enables the Amiga linker to correctly locate 
the translator library: 

struct Library *TranslatorBase; 

TranslatorBase = OpenLibrary ( "translator . library" , REVISION) ; 
if (TranslatorBase != NULL) 

{ 

/* use translator here -- library open */ 

} 

LIBS: must contain translator. library. Since translator is a disk-based library, the call to 
OpenLibraryO will work only if the LIBS: directory contains translator. library. 
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Using The Translate Functions 

Once the library is open, you can call the translate function: 

#define BUFLEN 500 

STRPTR EnglStr; /* pointer to sample input string */ 

LONG EnglLen; /* input length */ 

UBYTE PhonBuffer [BUFLEN] ; /* place to put the translation */ 

LONG rtnCode; /* return code from function */ 

EnglStr = "This is Amiga speaking."; /* a test string */ 

EnglLen = strlen (EnglStr) ; 

rtnCode = Translate (EnglStr, EnglLen, (STRPTR) &PhonBuffer [0] , BUFLEN); 

The input string will be translated into its phonetic equivalent and can be used to feed the narrator device. If you 
receive a non-zero return code, you haven't provided enough output buffer space to hold the entire translation. In 
this case, the Translate() function breaks the translation at the end of a word in the input stream and returns the 
position in the input stream at which the translation ended. You can use the output buffer, then call the 
Translate() function again, starting at this original ending position, to continue the translation where you left off. 
This method will sound smoothest if the ending position ends on sentence boundaries. 

TranslateQ returns negative values. To get the proper character offset, you must use 
-(rtnCode) as the starting point for a new translation. 

Closing the Translator Library 

As with all other libraries of functions, if you have successfully opened the translator library for use, be sure to 
close it before your program exits. If the system needs memory resources, it can then expunge closed libraries to 



gain additional memory space: 

struct Library *TranslatorBase; 

if (TranslatorBase) CloseLibrary (TranslatorBase) ; 

Additional Notes About Translate 

The English language has many words that do not sound the same as they are spelled. The translator library has 
exception rules that it consults as the translation progresses. It also provides for common abbreviations such as 
Dr., Prof., LB., etc. Words that are not in the exception table are translated literally. This translation allows 
unrestricted English text as input, and uses over four hundred and fifty context sensitive rules. It automatically 
accents content words, and leaves function words (e.g. of, by, the, and at) unaccented. It is possible, however, 
that certain words will not translate well. You can improve the quality of translation by handling those words on 
your own. 

The phoneme table that the narrator uses is listed in the "Narrator Device" chapter of the Amiga ROM Kernel 
Reference Manual: Devices. You will also find other important information about the Amiga's speech capability in 
the narrator chapter including a working example which shows how to use the translator library together with the 
narrator device. 
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Chapter 37 
Utility Library 



Utility library is the home for all the OS functions which don't fit in the other libraries. Among the calls in utility 
library are calls to manage tags and tag lists, callback hooks, and some generic 32-bit math functions, all 
discussed below. 



Tags 



The implementation of tags is one of the many new features of Release 2. Tags make it possible to add new 
parameters to system functions without interfering with the original parameters. They also make specifying 
parameter lists much clearer and easier. 

Tag Functions and Structures 

A tag is made up of an attribute/value pair as defined below (from <utility/tagitem.h>): 



struct Tagltem 

{ 

ULONG t i_Tag ; 
ULONG ti Data; 



/* identifies the type of this item */ 

/* type-specific data, can be a pointer */ 



The ti_Tag field specifies an attribute to set. The possible values of ti_Tag are implementation specific. System 
tags are defined in the include files. The value the attribute is set to is specified in ti_Data. An example of the 
attribute/value pair that will specify a window's name is: 

ti_Tag = WA_Title; 

ti_Data = "My Window's Name"; 

The ti_Data field often contains 32-bit data as well as pointers. 

These are brief descriptions of the utility functions you can use to manipulate and access tags. For complete 
descriptions, see the "Simple Tag Usage" and "Advanced Tag Usage" sections. 
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The following utility library calls are for supporting tags: 

Table 37-1 : Utility Library Tag Functions 



AllocateTagltemsO 
FreeTagltemsQ 



Allocate a Tagltem array (or chain). 
Frees allocated Tagltem lists. 



CloneTagltems() 
RefreshTagltemClonesQ 



Copies a Tagltem list. 

Rejuvenates a clone from the original. 



FindTagltem() 
GetTagDataQ 
NextTagltem() 
TaglnArrayQ 



Scans Tagltem list for a tag. 

Obtain data corresponding to tag. 

Iterate Tagltem lists. 

Check if a tag value appears in a Tag array. 



FilterTagChanges() 
FilterTagltemsO 
MapTags() 
PackBoolTags() 



Eliminate Tagltems which specify no change. 
Remove selected items from a Tagltem list. 
Convert ti_Tag values in a list via map pairing. 
Builds a "Flag" word from a Tagltem list. 



Simple Tag Usage 

One way tags are passed to system functions is in the form of tag lists. A tag list is an array or chain of arrays of 



Tagltem structures. Within this array, different data items are identified by the value of ti_Tag. Items specific to a 
subsystem (Intuition, Graphics,...) have a ti_Tag value which has the TAGJJSER bit set. Global system tags 
have a ti_Tag value with TAGJJSER bit clear. The global system tags include: 

Table 37-2: Global System Tags 



Tag Value Meaning 

TAG_IGNORE A no-op. The data item is ignored. 

TAG_MORE The ti_Data points to another tag list, to support 
chaining of Tagltem arrays. 

TAG_DONE Terminates the Tagltem array (or chain) . 

TAG_SKIP Ignore the current tag item, and skip the next n array 
elements, where n is kept in ti_Data. 



Note that user tags need only be unique within the particular context of their use. For example, the attribute tags 
defined for OpenWindow() have the same numeric value as some tags used by OpenScreen(), but the same 
numeric value has different meaning in the different contexts. 

System functions receive Tagltems in several ways. One way is illustrated in the Intuition function 
OpenWindow(). This function supports an extented NewWindow structure called ExtNewWindow. When the 
NWEXTENDED flag is set in the ExtNewWindow.Flags field, OpenWindow() assumes that the 
ExtNewWindow. Extension field contains a pointer to a tag list. 

Another method of passing a tag list is to directly pass a pointer to a tag list, as OpenWindowTagList() does in 
the following code fragment. 
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struct Tagltem tagitem[3] ; 
struct Screen *screen; 
struct Window *window; 

tagitem[0] . ti_Tag = WA_CustomScreen; 

tagitem[0] . ti_Data = screen; /* Open on my own screen */ 

tagitem[l] .ti_Tag = WA_Title; 

tagitem[l] . ti_Data = "RKM Test Window"; 

tagitem[2] .ti_Tag = TAG_DONE; /* Marks the end of the tag array. */ 

/* Use defaults for everything else. Will open as big as the screen. */ 
/* Because all window parameters are specified using tags, we don't */ 
/* need a NewWindow structure */ 

if (window = OpenWindowTagList (NULL, tagitem) ) 



{ 



} 



/* rest of code */ 
CloseWindow (window) 



Notice that window parameters need not be explicitly specified. Functions that utilize tags have reasonable 
defaults to fall back on in case no valid attribute/value pair was supplied for a particular parameter. This fall back 
capability is a useful feature. An application only has to specify the attributes that differ from the default, rather 
than unnecessarily listing all the possible attributes. 

The amiga.lib support library offers another way to pass Tagltems to a function. Rather than passing a tag list, 
the function OpenWindowTagsQ receives the attribute/value pairs in the argument list, much like printf() 
receives its arguments. Any number of attribute/value pairs can be specified. This type of argument passing is 
called VarArgs. The following code fragment illustrates the usage of OpenWindowTagsQ. 



struct Window *window; 

/* Just pass NULL to show we aren't using a NewWindow */ 



window = OpenWindowTags ( NULL, 

WA_CustomScreen, screen, 
WA_Title, "RKM Test Window", 
TAG_DONE ) ; 

Tags are not exclusively for use with the operating system; the programmer can implement them as well. The 
run-time utility library contains several functions to make using tags easier. 

Simple Tag Usage Example 

The following example shows simple usage of tags. It shows how to allocate a tag array and use it, it also shows 
how to build a tag array on the stack. 

;/* tagl.c - Execute me to compile me with SAS C 5.10 

LC -bl -cfis - j 73 tagl.c 

Blink FROM LIB : c . o, tagl . o TO tagl LIBRARY LIB : LC . lib, LIB : Amiga . lib 

quit 

• * 

** The following example shows simple usage of tags. It shows how to 
** allocate a tag array and use it, it also shows how to build a tag 
** array on the stack. 
*/ 

#include <exec/types .h> 
#include <exec/libraries . h> 
#include <utility/tagitem.h> 
#include <intuition/intuition.h> 
#include <clib/exec_protos . h> 
#include <clib/intuition_protos . h> 
#include <clib/utility_protos . h> 

extern struct Library *SysBase; 

struct Library *IntuitionBase, *UtilityBase; 

int main (int argc, char **argv) 

{ 

struct Tagltem *tags; 
struct Window *win; 

/* For this example we need Version 2.0 */ 

if (IntuitionBase = OpenLibrary ( "intuition. library" , 37)) 

{ 

/* We need the utility library for this example */ 

if (UtilityBase = OpenLibrary ( "utility . library" , 37)) 

{ 

/* This section allocates a tag array, fills it in with values, */ 
/* and then uses it. */ 

/* Allocate a tag array */ 

if (tags = AllocateTagltems (7)) 



{ 



/* Fill in our tag array */ 

tags[0] .ti_Tag = WA_Width; 

tags [0] . ti_Data = 320; 

tags [1] .ti_Tag = WA_Height; 

tags [1] .ti_Data = 50; 

tags [2] .ti_Tag = WA_Title; 

tags [2] . ti_Data = (ULONG) "RKM Tag Example 1"; 

tags [3] .ti_Tag = WA_IDCMP; 

tags [3] . ti_Data = IDCMP_CLOSEWINDOW; 

tags [4] . ti_Tag = WA_CloseGadget ; 

tags [4] . ti_Data = TRUE; 

tags [5] .ti_Tag = WA_DragBar; 

tags [5] . ti_Data = TRUE; 

tags [6] .ti_Tag = TAG_DONE; 

/* Open the window, using the tag attributes as the 
* only description. */ 



if (win = OpenWindowTagList (NULL, tags) ) 

{ 

/* Wait for an event to occur */ 
WaitPort (win->UserPort) ; 

/* Close the window now that we're done with it */ 
CloseWindow (win) ; 



/* Free the tag list now that we're done with it */ 
FreeTagltems (tags) ; 
} 

/* This section builds the tag array on the stack, and passes */ 
/* the array to a function. */ 

/* Now use the VarArgs (or stack based) version. */ 
if (win = OpenWindowTags ( NULL, 

WA_Width, 320, 

WA_Height, 50, 

WA_Title, (ULONG) "RKM Tag Example 1", 

WA_IDCMP, IDCMP_CLOSEWINDOW, 

WA_CloseGadget , TRUE, 

WA_DragBar , TRUE , 

TAG DONE) ) 



{ 



} 



} 



/* Wait for an event to occur */ 
WaitPort (win->UserPort) ; 

/* Close the window now that we're done with it */ 
CloseWindow (win) ; 



/* Close the library now */ 
CloseLibrary (UtilityBase) ; 



/* Close the library now that we're done with it */ 
CloseLibrary (IntuitionBase) ; 
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Advanced Tag Usage 

The previous section provided the background material necessary to start using tags. This section will show how 
to use the more advanced features of tags using functions within utility library. 

Creating a New Tag List 

The AllocateTagltemsO function can be used to create a new tag array ready for use. The tag array should be 
passed to FreeTagltems() when the application is done with it. 

struct Tagltem *tags; 
ULONG tags_needed; 

/* Indicate how many tags we need */ 
tags_needed = 10; 

/* Allocate a tag array */ 

if (tags = AllocateTagltems (tags_needed) ) 

{ 

/* . . .do something with the array. . . */ 

/* Free the array when your done with it */ 
FreeTagltems (tags) ; 
} 



Copying an Existing Tag List 

The CloneTagltems() function is used to copy an existing tag array into a new tag array. 

struct Tagltem *otags; /* Original tag array */ 
struct Tagltem *ntags; /* New tag array */ 

/* Make sure there is a Tagltem array */ 
if (otags) 

{ 

/* Copy the original tags into a new tag array */ 
if (ntags = CloneTagltems (otags) ) 

{ 

/* . . .do something with the array. . . */ 

/* Free the array when your done with it */ 
FreeTagltems (ntags) ; 
} 
} 

This function can also be used to implement a function that will insert tag items into an array. 

struct Tagltem *otags; /* Original tag array */ 
struct Tagltem *tags; /* New tag array */ 

/* Insert a couple of tags into an existing tag array */ 
if (tags = MakeNewTagList (GA_Lef tEdge, 10, 

GA_TopEdge , 2 0, 

TAG_M0RE, otags)) 

{ 

/* . . .do something with the array. . . */ 

/* Free the array when your done with it */ 
FreeTagltems (tags) ; 
} 

/* This function will create a tag array from tag pairs placed on 
* the stack */ 
struct Tagltem *MakeNewTagList (ULONG data,...) 

{ 

struct Tagltem *tags = (struct Tagltem *) &data; 

return (CloneTagltems (tags) ) ; 
} 
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Filtering an Existing Tag List 

Sometimes it is necessary to only allow certain attributes to be visible in a tag list. In order to achieve this, the tag 
array would need to be filtered. 

A number of functions are provided for filtering items in a tag array. They are FilterTagChanges(), 
FilterTagltems() and RefreshTagltemClones(). 

/* We want the text entry gadget to receive the following tags */ 
Tag string_attrs [] = 

{ " 

STRINGAJMaxChars , 
STRINGA_Buffer, 
STRINGA_TextVal , 
TAG_END , 

}; 

/* These are attributes that the model understands */ 
Tag model_attrs [] = 

{ 

CGTAJTotal, 

CGTAJVisible, 
CGTA_Top , 
ICA TARGET, 



ICA_MAP, 
TAG_END , 

}; 

struct Tagltem *otags; /* Original tag list */ 
struct Tagltem *ntags; /* New, work, tag list */ 

/* Make a copy of the original for us to work with */ 
ntags = CloneTagltems (otags) ; 

/* Create a tag list that only contains attributes that are 
* listed in the model_attrs list. */ 
if (FilterTagltems (ntags, model_attrs, TAGFILTER_AND) ) 

{ 

/* Work with filtered tag list (ntags) */ 

/* Restore the tag list */ 

Ref reshTagltemClones (ntags, otags); 

/* Create a tag list that only contains attributes that 

* aren't in the model_attrs list. */ 

if (FilterTagltems (ntags, model_attrs, TAGFILTER_NOT) ) 

{ 

/* Work with filtered tag list (ntags) */ 

} 

/* Restore the tag list */ 

Ref reshTagltemClones (ntags, otags); 

/* Create a tag list that only contains attributes that 

* are in the string_attrs list. */ 

if (FilterTagltems (ntags, string_attrs, TAGFILTER_AND) ) 

{ 

/* Work with filtered tag list (ntags) */ 

} 
} 

/* Free work tag list. */ 
FreeTagltems (ntags) ; 
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Locating an Attribute 
To see if an attribute is in a tag array, the TaglnArray() function is used. 

/* See if the listview labels attribute is located in a tag array */ 
if (TagltemArray (GTLV_Labels, tags)) 

{ 

/* Yes, the attribute is in the list */ 

} 

else 

{ 

/* No, the attribute isn't in the list */ 

} 

The FindTagltem() function will return a pointer to the actual tag that has the desired attribute. This allows you to 
manipulate the tag or to determine if the attribute exists but just has a NULL value. 

struct Tagltem *tag; 

/* See if they are trying to set a sound */ 
if (tag = FindTagItem(MGA_Sound, attrs) ) 

{ 

/* Set the sound attribute to point to the specified sound data */ 

tag->ti_Data = sound; 
} 

Sequential Access of Tag Lists 

In order to sequentially access the members of a tag array, the NextTagltemQ function is used. 



struct Tagltem *tags = msg->ops_AttrList ; 
struct Tagltem *tstate; 
struct Tagltem *tag; 
ULONG tidata; 

/* Start at the beginning */ 
tstate = tags; 

/* Step through the tag list while there are still items in the 

* list */ 
while (tag = NextTagltem (&tstate) ) 

{ 

/* Cache the data for the current element */ 
tidata = tag->ti_Data; 

/* Handle each attribute that we understand */ 
switch (tag->ti_Tag) 

{ 

/* Put a case statement here for each attribute that your 

* function understands */ 
case PGA_Freedom: 

lod->lod_Flags |= tidata; 
break; 

case GTLV_Labels: 

lod->lod_List = (struct List *) tidata; 
break; 

/* We don't understand this attribute */ 
default : 
break; 
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Random Access of Tag Lists 

The GetTagData() function will return the data for the specified attribute. If there isn't a tag that matches, then 
the default value is returned. 

APTR sound; 

/* Get the sound data that our function will use. */ 

sound = (APTR) GetTagData (MGA_Sound, (ULONG) Def aultSound, attrs) ; 

Obtaining Boolean Values 

Often times data is best represented as simple boolean (TRUE or FALSE) values. The PackBoolTags() function 
provides an easy method for converting a tag list to bit fields. 

/* These are the attributes that we understand, with the 

* corresponding flag value. */ 
struct Tagltem activation_bools [] = 

{ 

/* Attribute Flags */ 

{ GA_ENDGADGET , ENDGADGET } , 

{GA_IMMEDIATE, GADGIMMEDIATE } , 

{GA_RELVERIFY, RELVERIFY}, 

{ GA_FOLLOWMOUSE , FOLLOWMOUSE } , 

{GA_RIGHTBORDER, RIGHTBORDER} , 

{GA_LEFTBORDER, LEFTBORDER} , 

{GA_TOPBORDER, TOPBORDER}, 

{GA_BOTTOMBORDER, BOTTOMBORDER} , 

{GA_TOGGLESELECT, TOGGLESELECT} , 

/* Terminate the array */ 
{ TAG_END } 

}; 

/* Set the activation field, based on the attributes passed */ 
g->Activation = PackBoolTags (g->Activation, tags, activation_bools) ; 



Mapping Tag Attributes 

To translate all occurrences of an attribute to another attribute, the MapTags() function is used. 

For Release 2, the third parameter of this function is always TRUE (tags remain in the array even if they can't be 
mapped). 

struct Tagltem map_list [] = 

{ 

/* Original New */ 

{MGA_LeftEdge, GA_Lef tEdge} , 

{MGA_TopEdge, GA_TopEdge}, 

{MGA_Width, GA_Width} , 

{MGA_Height, GA_Height}, 



} 



/* Terminate the array */ 
{ TAG_END } , 



/* Map the tags to the new attributes, keeping all attributes that 

* aren't included in the mapping array */ 
MapTags (tags, map_list, TRUE); 
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Callback Hooks 

The callback features of Release 2 provide a standard means for applications to extend the functionality of 
libraries, devices, and applications. This standard makes it easy for the operating system to use custom modules 
from different high level programming languages as part of the operating system. For example, the layers library, 
which takes care of treating a display as a series of layered regions, allows an application to attach a pattern 
function to a display layer. Instead of filling in the background of a layer with the background color, the layers 
library calls the custom pattern function which fills in the layer display with a custom background pattern. 

Callback Hook Structure and Function 

An application passes a custom function in the form of a callback Hook (from <utility/hooks.h>): 

struct Hook 

{ 

struct MinNode h_MinNode; 

ULONG (*h_Entry) (); /* stub function entry point */ 
ULONG (*h_SubEntry) ( ) ; /* the custom function entry point */ 
VOID *h_Data; /* owner specific */ 

}; 

hMlnNode 

This field is reserved for use by the module that will call the Hook. 

h_Entry 

This is the address of the Hook stub. When the OS calls a callback function, it puts parameters for the 
callback function in CPU registers AO, A1 , and A2. This makes it tough for higher level language 
programmers to use a callback function because most higher level languages don't have a way to 
manipulate CPU registers directly. The solution is a stub function which first copies the parameters 
from the CPU registers to a place where a high level language function can get to them. The stub 
function then calls the callback function. Typically, the stub pushes the registers onto the stack in a 
specific order and the callback function pops them off the stack. 

h_SubEntry 

This is the address of the actual callback function that the application has defined. The stub calls this 
function. 



Data 



This field is for the application to use. It could point to a global storage structure that the callback 
function utilizes. 



There is only one function defined in utility library that relates to callback hooks: 

ULONG CallHookPkt (struct Hook *hook, VOID *object, VOID *paramPkt) ; 

This function calls a standard callback Hook function. 
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Simple Callback Hook Usage 

A Hook function must accept the following three parameters in these specific registers: 

AO - Pointer to the Hook structure. 

A2 - Pointer to an object to manipulate. The object is context specific. 

A1 - Pointer to a message packet. This is also context specific. 

For a callback function written in C, the parameters should appear in this order: 

myCallbackFunction (Pointer to Hook (AO), 

Pointer to Object (A2) , 
Pointer to message (Al) ) ; 

This is because the standard C stub pushes the parameters onto the stack in the following order: A1 , A2, AO. The 
following assembly language routine is a callback stub for C: 

INCLUDE 'exec/types . i' 
INCLUDE 'utility/hooks.i' 





hookEntry 






Entry: 








move . 1 


al, - (sp) 




push message packet pointer 


move . 1 


a2, - (sp) 




push object pointer 


move . 1 


aO, - (sp) 




push hook pointer 


move . 1 


h SubEntry 


aO) ,a0 


fetch actual Hook entry point 


jsr 


(aO) 




and call it 


lea 


12 (sp) , sp 




fix stack 


rts 









If your C compiler supports registerized parameters, your callback functions can get the parameters directly from 
the CPU registers instead of having to use a stub to push them on the stack. The following C language routine 
uses registerized parameters to put parameters in the right registers. This routine requires a C compiler that 
supports registerized parameters. 

#include <exec/types .h> 
#include <utility/hooks .h> 

#define ASM asm 

#define REG(x) register ## x 

/* This function converts register-parameter hook calling 

* convention into standard C conventions. It requires a C 

* compiler that supports registerized parameters, such as 

* SAS/C 5. xx or greater. 

*/ 

ULONG ASM 

hookEntry (REG (aO) struct Hook *h, REG(a2) VOID *o, REG(al) VOID *msg) 

{ 

return ( (*h->h_SubEntry) (h, o, msg) ) ; 

} 

A callback function is executed on the context of the module that invoked it. This usually means that callback 
functions cannot call functions that need to look at environment specific data. For example, printf() needs to look 
at the current process's input and output stream. Entities like Intuition have no input and output stream. This also 
means that in order for the function to access any of its global data, it needs to make sure the CPU can find the 
function's data segment. It does this by forcing the function to load the offset for the program's data segment into 
CPU register A4. See your compiler documentation for details. 
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The following is a simple function that can be used in a callback hook. 

ULONG MyFunction (struct Hook *h, VOID *o, VOID *msg) 

{ 

/* A SASC and Manx function that obtains access to the global 

data segment */ 
geta4 ( ) ; 

/* Debugging function to send a string to the serial port */ 
KPrintF ( "Inside MyFunction () \n" ) ; 



return (1) ; 



} 



The next step is to initialize the Hook for use. This basically means that the fields of the Hook structure must be 
filled with appropriate values. 

The following simple function initializes a Hook structure. 

/* This simple function is used to initialize a Hook */ 
VOID InitHook (struct Hook *h, ULONG (*func)(), VOID *data) 

{ 

/* Make sure a pointer was passed */ 
if (h) 

{ 

/* Fill in the hook fields */ 

h->h_Entry = (ULONG (*)()) hookEntry; 

h->h_SubEntry = func; 

h->h_Data = data; 
} 
} 

The following is a simple example of a callback hook function. 

;/* hooksl.c - Execute me to compile me with SAS C 5.10 

LC -bl -cfis -J73 hooksl.c 

Blink FROM LIB : c . o, hooksl . o TO hooksl LIBRARY LIB : LC . lib, LIB : Amiga . lib 

quit 

*/ 

#include <exec/types .h> 
#include <exec/libraries . h> 
#include <utility/hooks . h> 
#include <dos.h> 

#include <clib/exec_protos . h> 
#include <clib/dos_protos . h> 
#include <clib/utility_protos . h> 

#include <stdio.h> 

extern struct Library *SysBase; 
struct Library *UtilityBase; 

#define ASM asm 

#define REG(x) register ## x 

/* This function converts register-parameter Hook calling 

* convention into standard C conventions. It requires a C 

* compiler that supports registerized parameters, such as 

* SAS/C 5. xx or greater. 
*/ 

ULONG ASM 

hookEntry (REG (aO) struct Hook *h, REG(a2) VOID *o, REG(al) VOID *msg) 

{ 

return ((*(ULONG (*) (struct Hook *,VOID *,VOID * ) ) (h->h_SubEntry) ) (h, o, msg) ) ; 

} 



/* This simple function is used to initialize a Hook */ 
VOID InitHook (struct Hook *h, ULONG (*func)(), VOID *data) 

{ 

/* Make sure a pointer was passed */ 
if (h) 

{ 

/* Fill in the Hook fields */ 
h->h_Entry = (ULONG (*)()) hookEntry; 
h->h_SubEntry = func; 
h->h_Data = data; 
} 
} 

/* This function only prints out a message indicating that we are 
* inside the callback function. 
*/ 

ULONG MyFunction (struct Hook *h, VOID *o, VOID *msg) 

{ 

/* Obtain access to the global data segment */ 
geta4 ( ) ; 

/* Debugging function to send a string to the serial port */ 
printf ( " Inside MyFunction ( ) \n" ) ; 



} 



return (1) ; 



int main (int argc, char **argv) 

{ 

struct Hook h; 

/* Open the utility library */ 

if (UtilityBase = OpenLibrary ( "utility . library" , 36)) 

{ 

/* Initialize the callback Hook */ 
InitHook (&h, MyFunction, NULL) ; 

/* Use the utility library function to invoke the Hook */ 
CallHookPkt (&h, NULL, NULL) ; 

/* Close utility library now that we're done with it */ 
CloseLibrary (UtilityBase) ; 

} 

else printf ("Couldn't open utility . library\n" ) ; 

} 

32-bit Integer Math Functions 

Utility library contains some high-speed math functions for 32-bit integer division and multiplication. These 
functions will take advantage of available processor instructions (like DIVUL), if a 68020 processor or higher is 
present. If not, these functions will mimic those instructions in 68000 only instructions, thus providing processor 
independency. 

Currently the following functions are implemented: 



SDivMod32() Signed 32 by 32-bit division and modulus. 

SMult32() Signed 32 by 32-bit multiplication. 

UDivMod32() Unsigned 32 by 32-bit division and modulus. 

UMult32() Unsigned 32 by 32-bit multiplication. 



Table 37-3: Utility Library 32-bit Math Functions 
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The division functions return the quotient in DO and the remainder in D1 . To obtain the remainder in a higher level 
language, either a compiler specific instruction to fetch the contents of a specific register must be used (like 
getregQ in SAS C) or a small assembler stub. 



Following a simple example of the usage of the 32-bit integer math functions in C. 

;/* uptime. c - Execute me to compile me with SAS C 5.10 

LC -bl -cfis - j 73 uptime. c 

Blink FROM LIB : c . o, uptime . o TO uptime LIBRARY LIB : LC . lib, LIB : Amiga . lib 

quit 

*/ 

/* Uses SAS C getregO */ 

#include <exec/types .h> 
#include <exec/memory . h> 
#include <dos/dos.h> 
#include <dos/dosextens .h> 
#include <dos/datetime . h> 
#include <utility/date . h> 
#include <dos.h> 

#include <clib/exec_protos . h> 
#include <clib/dos_protos . h> 
#include <clib/utility_protos . h> 

#include <stdlib.h> 

struct Library *UtilityBase; 

LONG main (void) ; 

LONG main (void) 

{ 

struct InfoData *infodata; 

struct DeviceList *ramdevice; 

struct DateStamp 'now; 

LONG currenttime, boottime; 

BPTR lock; 

LONG vargs [3] ; 

LONG re = RETURN_FAIL; 

/* Fails silently if < 37 */ 

if (UtilityBase = OpenLibrary ( "utility . library" , 37)) 

{ 

if (infodata = AllocMem (sizeof (struct InfoData), MEMF_CLEAR) ) 

{ 

if (now = AllocMem (sizeof (struct DateStamp), MEMF_CLEAR) ) 

{ 

if (lock = Lock ("RAM:", SHARED_LOCK) ) 

{ 

if ((Info (lock, infodata)) == DOSTRUE) 

{ 

/* Make C pointer */ 

ramdevice = BADDR (inf odata->id_VolumeNode) ; 

boottime = SMult32 (ramdevice->dl_VolumeDate .ds_Days, 86400) 
SMult32 (ramdevice->dl_VolumeDate .ds_Minute, 60) - 
SDivMod3 2 (ramdevice->dl_VolumeDate .ds_Tick, 
TICKS_PER_SECOND ) ; 

DateStamp (now) ; 

currenttime = SMult32 (now->ds_Days , 86400) + 
SMult32 (now->ds_Minute, 60) + 
SDivMod32 (now->ds_Tick, TICKS_PER_SECOND) ; 

currenttime -= boottime; 

if (currenttime > 0) 

{ 

vargs [0] = UDivMod32 (currenttime, 86400); 

vargs [1] = getreg(l); 

vargs [1] = UDivMod32 (vargs [1] , 3600); 



vargs [2] =getreg (1) ; 

vargs[2] = UDivMod32 (vargs [2] , 60); 

/* 

* Passing the address of the array allows the VPrintf () 

* function to access the array contents. Keep in mind 

* that VPrintf () does _N0T_ know how many elements are 

* really valid in the final parameter, and will gleefully 

* run past the valid arguments. 

*/ 

VFPrintf (Output ( ) , 

"up for %ld days, %ld hours, %ld minutes\n", 
vargs ) ; 

re = RETURN_0K; 
} 
} 
UnLock (lock) ; 

} 

FreeMem(now, sizeof (struct DateStamp) ) ; 

} 

FreeMem (inf odata, sizeof (struct Inf oData) ) ; 

} 

CloseLibrary (UtilityBase) ; 

} 

exit (re) ; 

} 

International String Functions 

The international string functions in utility library are a way to make use of a future localization library which 
Commodore-Amiga will provide. When the localization library is opened, the functions will be replaced by ones 
which will take the locale as defined by the user into account. This means that the compare order may change 
according to the locale, so care should be taken not to rely on obtaining specific compare sequences. 

Currently implemented are: 



Stricmp() 


Compare string case-insensitive. 




StrnicmpO 


Compare string case-insensitive, with 


a specified length. 


ToLower() 


Convert a character to lower case. 




TollpperQ 


Convert a character to upper case. 





Table 37-4: Utility Library International String Functions 

These functions operate in the same manner as their ANSI C equivalents, for the most part. For more 
information, see the "Utility Library" Autodocs in the Amiga ROM Kernel Reference Manual: Includes and 
Autodocs. Here is a simple example of the usage of the international string functions. 

;/* istr.c - Execute me to compile me with SAS C 5.10 

LC -bl -cfis - j 73 istr.c 

Blink FROM LIB : c . o, istr . o TO istr LIBRARY LIB : LC . lib, LIB : Amiga . lib 

quit 

*/ 

#include <exec/types . h> 
#include <stdio.h> 
#include <string.h> 

#include <clib/exec_protos . h> 
#include <clib/utility_protos . h> 

void main (void) ; 

struct Library *UtilityBase; 

void main (void) 

{ 

UBYTE *butter = "Batervloot " ; 
UBYTE *bread = "Knackerbr0t " ; 



result ) 



UBYTE chl , ch2 ; 
LONG result; 

/* Fails silently if < 37 */ 

if (UtilityBase = OpenLibrary ( "utility . library" , 37)) 

{ 

result = Stricmp (butter , bread); 

printf ( "comparing %s with %s yields %ld\n", butter, bread, result ) ; 

result = Strnicmp (bread, butter, strlen (bread) ) ; 

printf ( "comparing (with length) %s with %s yields %ld\n", bread, butter, 

chl = ToUpper (0xE6) ; ae /* ASCII character 230 ae ligature */ 
ch2 = ToLower (OxDO) ; D /* ASCII character 208 Icelandic Eth */ 



} 
} 



printf ( "Chars %c %c\n", chl, ch2); 



Date Functions 



To ease date-related calculations, the utility library has some functions to convert a date, specified in a 
ClockData structure, in the number of seconds since 00:00:00 01-Jan-78 and vice versa. To indicate the date, 
the ClockData structure (in <utility/date.h>) is used. 

struct ClockData 

{ 

UWORD sec; /* seconds (0 - 59)*/ 

UWORD min; /* minutes (0 - 59) */ 

UWORD hour; /* hour (0 - 23) */ 

UWORD mday; /* day of the month (1 - 31) */ 

UWORD month; /* month of the year (1 - 12) */ 

UWORD year; /* 1978 - */ 

UWORD wday; /* day of the week (0 - 6, where is Sunday) */ 

}; 
The following functions are available to operate on ClockData: 



Amiga2Date() Calculate the date from the specified timestamp (in seconds). 

CheckDate() Check the legality of a date. 

Date2Amiga() Calculate the timestamp from the specified date. 



Table 37-5: Utility Library Date Functins 

Amiga2Date() takes a number of seconds from 01-Jan-78 as argument and fills in the supplied ClockData 
structure with the date and time. 

CheckDate() checks if the supplied ClockData structure is valid, and returns the number of seconds from 
01 -Jan-78 if it is. Note that this function currently does not take the supplied day of the week in account. 

Date2Amiga() takes a ClockData structure as argument and returns the number of seconds since 01 -Jan-78. 
The supplied ClockData structure MUST be valid, since no checking is done. 
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The following example shows various uses of the utility library date functions. 

;/* a2d.c - Execute me to compile me with SAS C 5.10 

LC -bl -cfis -j73 a2d.c 

Blink FROM LIB : c . o, a2d. o TO a2d LIBRARY LIB : LC . lib, LIB : Amiga . lib 

quit 

*/ 

#include <exec/types .h> 
#include <exec/memory .h> 
#include <dos/datetime .h> 



#include <devices/timer . h> 

#include <clib/exec_protos . h> 
#include <clib/timer_protos . h> 
#include <clib/utility_protos . h> 

#include <stdio.h> 

LONG main (void) ; 

struct Library *TimerBase; 
struct Library *UtilityBase; 

LONG main (void) 

{ 

struct ClockData *clockdata; 
struct timerequest *tr; 
struct timeval *tv; 
LONG seconds ; 

if (UtilityBase = OpenLibrary ( "utility . library" , 37)) 

{ 

if (tr = AllocMem (sizeof (struct timerequest), MEMF_CLEAR) ) 

{ 

if (tv = AllocMem(sizeof (struct timeval), MEMF_CLEAR) ) 

{ 

if (clockdata = AllocMem (sizeof (struct ClockData), MEMF_CLEAR) ) 

{ 

if (! (OpenDevice ( "timer .device" , UNIT_VBLANK, (struct IORequest *)tr, 0) )) 

{ 

TimerBase = tr->tr_node . io_Device; 

GetSysTime (tv) ; 

printf ( "GetSysTime ( ) : \t%d %d\n", tv->tv_secs, tv->tv_micro) ; 

Amiga2Date (tv->tv_secs, clockdata) ; 

printf ( "Amiga2Date ( ) : sec %d min %d hour %d\n", clockdata->sec, 
clockdata- >min, clockdata- >hour) ; 

printf (" mday %d month %d year %d wday %d\n", clockdata->mday, 

clockdata- >month, clockdata- >year, clockdata- >wday) ; 

seconds = CheckDate (clockdata) ; 

printf ( "CheckDate ( ) :\t%ld\n", seconds) ; 

seconds = Date2Amiga (clockdata) , • 

printf ( "Date2Amiga ( ) :\t%ld\n", seconds) ; 

CloseDevice ( (struct IORequest *)tr); 

} 

FreeMem (clockdata, sizeof (struct ClockData)); 

} 

FreeMem(tv, sizeof (struct timeval)); 

} 

FreeMem(tr, sizeof (struct timerequest)); 

} 

CloseLibrary (UtilityBase) ; 

} 
} 
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Function Reference 

The tables which follow contain breif descriptions of the functions inside the utility library. All these functions 
require Release2 or a later version of the Amiga operating system. See the Amiga ROM Kernel Reference 



Manual: Includes and Autodocs for details on each function call. 



Tag Function Reference 

The following are brief descriptions of the utility library functions which pertain to tags and tag lusts. 

Table 37-6: Utility Tag Functions 



Function 



Description 



AllocateTagltemsO 
FreeTagltems() 



Allocate a Tagltem array (or chain). 
Frees allocated Tagltem lists. 



CloneTagltems() 
RefreshTagltemClonesQ 



Copies a Tagltem list. 

Rejuvenates a clone from the original. 



FindTagltem() 
GetTagData() 
NextTagltem() 
TaglnArray() 



Scans Tagltem list for a tag. 

Obtain data corresponding to tag. 

Iterate Tagltem lists. 

Check if a tag value appears in a Tag array. 



hiiter I aguhanges() 
FilterTagltemsO 
MapTags() 
PackBoolTagsQ 



biiminate lagitems which specify no change. 
Remove selected items from a Tagltem list. 
Convert ti_Tag values in a list via map 
Builds a "Flag" word from a Tagltem list. 



Callback Hook Function Reference 

The following are brief descriptions of the utility library functions which pertain to callback hooks. 

Table 37-7: Utility Hook Functions 
hunction 



CallHookPkt() 



Description 

(Jail a standard callback hook tunction. 



32-Bit Integer Math Function Reference 

The following are brief descriptions of the utility library functions which pertain to 32-bit integer math. 

Table 37-8: Utility 32-Bit Math Functions 



Function 



SDivMod32() 
SMult32() 
UUivMod32() 
UMult32() 



Description 



Signed 32 by 32-bit division and modulus. 
Signed 32 by 32-bit multiplication, 
unsigned 6Z oy '6Z-o\\ aivision moauius 
Unsigned 32 by 32-bit multiplication. 
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International String Function Reference 

The following are brief descriptions of the utility library functions which pertain to string operations using the 
international ASCII character set. 

Table 37-9: Utility International String Functions 



Function 
stricmpo 
StrnicmpO 
i oLowery 
ToUpperQ 



Description 



uompare strings, case-insensitive. 

Compare strings, case-insensitive, with specified length. 

uonvert a character to lower case. 

Convert a character to upper case. 



Date Function Reference 

The following are brief descriptions of the utility library functions which pertain to date conversion. 



Table 37-10: Utility Date Functions 



Function Description 

CheckL)ate() Check the legality ot a date. 



Amiga2Date() Calculate the date from a specified timestamp. 

Date2Amiga() Calculate the timestamp from a specified date. 
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Appendix A 
Linker Libraries 



This section describes the amiga.lib and debug. lib libraries. Unlike the libraries described in the other chapters of 
the manual, these are not shared run-time libraries. Code from the linker libraries is inserted by the linker into 
your final program. Only the functions you use are pulled into your code. These libraries are typically supplied by 
your language or compiler vendor. 

Amiga.lib 

This is the main Amiga scanned linker library, linked with most programs for the Amiga. The major components of 
amiga. lib are: 

• stubs Functions for each Amiga ROM routine that copy arguments from the stack to the CPU registers -- 

thereby enabling stack-based C compilers to call register-based Amiga ROM routines. 

• offsets The negative offset from the library base for each Amiga function. These are called Library Vector 

Offsets (_LVO). 

• Exec C functions which simplify many Exec procedures such as the creation and deletion of tasks, ports, and 

I/O request structures. 

• clib C support functions including pseudo-random number generation and a limited set of file and stdio 

functions designed to work directly with AmigaDOS file handles. 

• Math C functions which provide some basic conversions to and from Fast Floating Point (FFP) format 

numbers. 

• Graphics C support functions to add and remove tasks from the vertical-blanking interval interrupt server 

chain. 

• ARexx C support functions for ARexx variable handling and message checking. 
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NOTE: The Timer, Commodities, and Intuition support functions listed below are valid only for 
use with Release 2.04 (V37) or a later version of the system software. 

• Timer C support functions to do common timer device operations. 

• Commodities C functions which support the Commodities system. Included are functions to deal with 

ToolTypes, and to create various Commodities objects. 

• Intuition Functions which provide support for Intuition's hook and Boopsi sub-systems. 

Debug. lib 

This link library contains standard I/O (stdio) style functions for communicating with a serial terminal connected to 
the Amiga via its built-in serial port. Typically this terminal will be a 9600-baud, 8 data-bits, one stop-bit 
connection to an external terminal or an Amiga running a terminal package. The debug. lib functions allow you to 
output messages and prompt for input (even from within low level task or interrupt code) without disturbing the 
Amiga's display and or current state (other than the serial hardware itself). 

No matter how badly the system may have crashed, these functions can usually get a message out. A similar 
debugging library (currently called ddebug.lib) is available for sending debugging output to the parallel port. This 
is useful for debugging serial applications. Ddebug.lib is not documented here. It contains functions similar to 
debug. lib but with names starting with 'D' instead of 'K'. 

Please refer to the Amiga ROM Kernel Reference Manual: Includes and Autodocs for a detailed description of the 



function. 



Amiga.lib 



Amiga. lib is the main linker library. Most applications link with and use at least one function in amiga.lib. The 
functions available are as follows. 

Exec Support 

BeglnlOO 

This function takes an lORequest and passes it directly to the BEGINIO vector of the proper device. 
This works exactly like SendlO(), but does not clear the io_Flags field first. This function does not wait 
for the I/O to complete. 

CreateExtlO() and DeleteExtlO() 

CreateExtlO() allocates memory for and initializes a new I/O request block of a program-specified 
number of bytes. The number of bytes must be the size of a legal lORequest (or extended request) or 
very nasty things will happen. DeleteExtlOQ frees up an I/O request as allocated by CreateExtlO(). 
The mn_Length field determines how much memory to deallocate. 
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CreatePort() and DeletePort() 

CreatePort() allocates and initializes a new message port. The message list of the new port will be 
prepared for use via NewListQ. The port will be set to signal your task when a message arrives 
(PA_SIGNAL). DeletePort() deletes the port created by CreatePort(). All messages that may have 
been attached to that port must already have been replied to. 

CreateStdlO() and DeleteStdlO() 

CreateStdlO() allocates memory for and initializes a new lOStdReq structure. DeleteStdlOQ frees up 
an lOStdReq allocated by CreateStdlO(). 

CreateTask() and DeleteTask() 

These functions simplify creation and deletion of subtasks by dynamically allocating and initializing the 
required structures and stack space. They also add the task to Exec's task list with the given name and 
priority. A tc_MemEntry list is provided so that all stack and structure memory allocated by 
CreateTask() is automatically deallocated when the task is removed. Before deleting a task with 
DeleteTask(), you must first make sure that the task is not currently executing any system code which 
might try to signal the task after it is gone. 

NewLlst() 

Prepares a List structure for use; the list will be empty and ready to use. 

CLIB 

FastRand() 

Generates a pseudo-random number. The seed value is taken from stack, shifted left one position, 
exclusive-or'ed with hex value $1 D872B41 and returned. 

RangeRand() 

RangeRand() accepts a value from 1 to 65535, and returns a value within that range (a 16-bit integer). 
Note that this function is implemented in C. 



fclose() 

fgetc() 

fprintf() 



Closes a file. 



Gets a character from a file. 



Prints a formatted output line to a file. 



fputc() 

Puts character to file. 

fputs() 

Writes a string to file. 

getchar() 

Gets a character from stdin. 

printf() 

Puts format data to stdout. 

putchar() 

Puts character to stdout. 

puts() 

Puts a string to stdout, followed by newline. 

sprintf() 

Formats data into a string (see Exec RawDoFmtQ ). 



Math 

afp() 

arnd() 

dbf() 

fpa() 
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Converts ASCII string variable into fast floating-point. 

ASCII round-off of the provided floating-point string. 

Accepts a dual-binary format floating-point number and converts it to FFP format. 



Accepts an FFP number and the address of the ASCII string where its converted output is to be stored. 
The number is converted to a NULL terminated ASCII string and stored at the address provided. 
Additionally, the base ten (10) exponent in binary form is returned. 



Graphics 

AddTOF() and RemTOF() 

AddTOF() adds a task to the vertical-blanking interval interrupt server chain. This frees C programmers 
from the burden of having to write an assembly language routine to perform this function. The task can 
be removed with RemTOF(). 

GetRexxVar() and SetRexxVar() 

GetRexxVarQ attempts to extract the value of a variable from a running ARexx script/program. 
SetRexxVar() will attempt to set the value of a particular variable in a running ARexx script. 

ARexx 

CheckRexxMsg() 

This function checks to make sure that a RexxMsg is from ARexx directly. Messages used by the Rexx 
Variable Interface (RVI) routines are required to be directly from ARexx. 

Timer 

TlmeDelayO 

This function waits for a specified period of time before returning to the the caller. 



Commodities 

ArgArraylnit() and ArgArrayDone() 

ArgArraylnit() returns an array of strings suitable for sending to icon.library/FindToolType(). This 
array will be the ToolTypes array of the program's icon, if it was started from Workbench. It will just be 
'argv' if the program was started from a shell. ArgArrayDone() frees memory and does cleanup 
required after a call to ArgArraylnit(). 

Arglnt() and ArgStringO 

These functions look for a particular entry in a ToolType array returned by ArgArraylnit() and return 
the integer (Arglnt()) or string (ArgStringO) associated with that entry. A default value can be passed 
to each function which will be returned in the event that the requested entry could not be found in the 
ToolType array. 
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CxCustom() 

This function creates a custom commodity object. The action of this object on receiving a commodity 
message is to call a function of the application programmer's choice. 

CxDebugO 

This function creates a Commodities debug object. The action of this object on receiving a 
Commodities message is to print out information about the message through the serial port (using the 
debug. Mb/KprintF() routine). A specified 'id' will also be displayed. 

CxFilter() 

Creates a Commodities input event filter object that matches a description string. The description string 
is in the same format as strings expected by commodities.library/SetFilter(). If the description string 
is NULL, the filter will not match any messages. 

CxSender() 

This function creates a Commodities sender object. The action of this object on receiving a 
Commodities message is to copy the Commodities message into a standard Exec Message, to put a 
supplied id in the message as well, and to send the message off to the message port. 

CxSignal() 

This function creates a Commodities signal object. The action of this object on receiving a Commodities 
message is to send a signal to a task. The caller is responsible for allocating the signal and determining 
the proper task ID. 

CxTranslate() 

This function creates a Commodities translator object. The action of this object on receiving a 
Commodities message is to replace that message in the commodities network with a chain of 
Commodities input messages. 

HotKey() 

This function creates a triad of commodity objects to accomplish a high-level function. 

The three objects are a filter, which is created to match by CxFilter(), a sender created by CxSender(), 
and a translator which is created by CxTranslateQ, so that it swallows any commodity input event 
messages that are passed down by the filter. 

This is the simple way to get a message sent to your program when the user performs a particular input 
action. 

InvertStringO 

This function returns a linked list of input events which would translate into the string using the supplied 
keymap (or the system default keymap if the supplied keymap is NULL). 

This chain should eventually be freed using FreelEvents(). 

FreelEvents() 

This function frees a linked list of input events as obtained from lnvertString(). 
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Intuition 

CallHook() and CallHookA() 

These functions invoke hooks. CallHook() expects a parameter packet ("message") on the stack, 
while CallHookA() takes a pointer to the message. 

DoMethod() and DoMethodA() 

Boopsi support functions that ask a specified Boopsi object to perform a specific message. The 
message is passed in the function call for DoMethodA() and on the stack for DoMethod(). The 
message is invoked on the object's true class. 

DoSuperMethod() and DoSuperMethodA() 

Boopsi support functions that ask a Boopsi object to perform a supplied message as if it was an 
instance of its superclass. The message is passed in the function call for DoSuperMethodA() and on 
the stack for DoSuperMethod(). 

CoerceMethod() and CoerceMethodA() 

Boopsi support functions that ask a Boopsi object to perform a supplied message as if it was an 
instance of some other class. The message is passed in the function call for CoerceMethodA() and on 
the stack for CoerceMethod. 

SetSuperAttrs() 

Boopsi support function which invokes the OM_SET method on the superclass of the supplied class for 
the supplied object. Allows the ops_AttrList to be supplied on the stack (i.e. in a varargs way). 



Debug. lib 



Debug. lib is a link library that provides useful diagnostic functions that are handy for developing code. It includes 
the following functions: 

KCmpStr() 

Compare two null-terminated strings. 

KGetChar() 

Get a character from the console. 

KGetNum() 

Get a number from the console. 

KMayGetChar() 

Return a character if present, but don't wait. 

KPrintF() 

Print formatted data to the console. 

KPutChar() 

Put a character to the console. 

KPutStr() 

Put a string to the console. 
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Appendix D 

Troubleshooting Your Software 

Many Amiga programming errors have classic symptoms. This guide will help you to eliminate or avoid these 
problems in your software. 

Audio - Corrupt Samples 

The bit data for audio samples must be in Chip RAM. Check your compiler manual for directives or 
flags which will place your audio sample data in Chip RAM. Or dynamically allocate Chip RAM and 
copy or load the audio sample there. 

Character Input/Ouput Problems 

RAWKEY users must be aware that RAWKEY codes can be different letters or symbols on national 
keyboards. If you need to use RAWKEY, run the codes through RawKeyConvert() (see the "Intuition 
Input and Output Methods" chapter) to get proper translation to correct ASCII codes. Improper display 
or processing of high-ASCII international characters can be caused by incorrect tolower()/toupper(), or 
by sign extension of character values when switched on or assigned into larger size variables. Use 
unsigned variables such as UBYTE (not char) for strings and characters whenever possible. 
Internationally correct string functions are provided in the 2.0 utility.library. 

CLI Error Message Problems 

Improper error messages are caused by calling exit(n) with an invalid or missing return value n. 
Assembler programmers using startup code should jump to the startup code's _exit with a valid return 
value on the stack. Programs without startup code should return with a valid value in DO. Valid return 
values such as RETURNJDK, RETURN_WARN, RETURN_FAIL are defined in <dos/dos.h> and 
<dos/dos.h>. Values outside of these ranges (-1 for instance) can cause invalid CLI error messages 
such as "not an object module". Useful hint — if your program is called from a script, your valid return 
value can be conditionally branched on in the script (i.e., call program, then perform actions based on 
IF WARN or IF NOT WARN). RETURN_FAIL will cause the script to stop if a normal FAILAT value is 
being used in script. 

CLI Won't Close on RUN 

A CLI can't close if a program has a Lock() on the CLI input or output stream ("*"). If your program is 
RUN >NIL: from a CLI, that CLI should be able to close unless your code or your compiler's startup 
code explicitly opens "*". 
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Crashes and Memory Corruption 

Memory corruption, address errors, and illegal instruction errors are generally caused by use of an 
uninitialized, incorrectly initialized, or already freed/closed pointer or memory. You may be using the 
pointer directly, or it may be one that you placed (or forgot to place) in a structure passed to system 
calls. Or you may be overwriting one of your arrays, or accidentally modifying or incrementing a pointer 
later used in a free/close. Be sure to test the return of all open/allocation type functions before using 
the result, and only close/free things that you successfully opened/allocated. Use watchdog/torture 
utilities such as Enforcer and MungWallm combination to catch use of uninitialized pointers or freed 
memory, and other memory misuse problems. Use the debugging tool TNTlo get additional debugging 
information instead of a Software Error requester. You may also be overflowing your stack-your 
compiler's stack checking option may be able to catch this. Cut stack usage by dynamically allocating 
large structures, buffers, and arrays which are currently defined inside your functions. 

Corruption or crashes can also be caused by passing wrong or missing arguments to a system call (for 
example SetAPen(3) or SetAPen(win,3), instead of SetAPen(rp,3)). C programmers should use 
function prototypes to catch such errors. If using short integers be sure to explicitly type long constants 
as long (e.g., 42L). (For example, with short ints, 1 « 17 may become zero). If corruption is occurring 
during exit, use printf() (or KPrintF(), etc.) with Delay(n) to slow down your cleanup and broadcast 
each step. A bad pointer that causes a system crash will often be reported as an standard 680x0 
processor exception $00000003 or 4, or less often a number in the range of $00000006-B. Or an 
Amiga-specific alert number may result. See <exec/alerts.h> for Amiga-specific alert numbers. Also 
see "Crashes-After Exit" below. 



Crashes - After Exit 

If this only happens when you start your program from Workbench, then you are probably UnLock()ing 
one of the WBStartup message wa_Locks, or UnLockQing the LockQ returned from an initial 
CurrentDirQ call. If you CurrentDir(), save the lock returned initially, and CurrentDirQ back to it 
before you exit. Only UnLockQ locks that you created. 

If you are crashing from both Workbench and CLI, and you are only crashing after exit, then you are 
probably either freeing/closing something twice, or freeing/closing something your did not actually 
allocate/open, or you may be leaving an outstanding device I/O request or other wakeup request. You 
must abort and WaitlO() any outstanding I/O requests before you free things and exit (see the 
Autodocs for your device, and for Exec AbortlOQ and WaitlOQ). Similar problems can be caused by 
deleting a subtask that might be in a WaitTOF(). Only delete subtasks when you are sure they are in a 
safe state such as Wait(OL). 

Crashes - Only on 68000 and 68010 

This can be caused by illegal instructions (80000000.00000004) such as new 68020/30/40 instructions 
or inline 68881/882 code. But this is usually caused by a word or longword access at an odd address. 
This is legal on the 68020 and above, but will generate an Address Error (80000000.00000003) on a 
68000 or 68010. This can be caused by using uninitialized pointers, using freed memory, or using 
system structures improperly (for example, referencing into lntuiMessage->IAddress as a struct 
Gadget * on a non-Gadget message). 

Crashes - Only on 68040 

Because of the instruction pipelining of the 68040, it is very difficult to recover from a bus error. If your 
program has an "Enforcer hit" (i.e., an illegal reference to memory), the resulting 68040 processor bus 
error will probably crash the machine. Use Enforcer (on an '030) to track down your problems, then 
correct them. 
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Crashes - Subtasks, Interrupts 

If part of your code runs on a different stack or the system stack, you must turn off compiler 
stack-checking options. If part of your code is called directly by the system or by other tasks, you must 
use long code/long data or use special compiler flags or options to assure that the correct base 
registers are set up for your subtask or interrupt code. 

Crashes - Window Related 

Be careful not to CloseWindow() a window during a while(msg=GetMsg(...)) loop on that window's port 
(next GetMsg() would be on freed pointer). Also, use ModifylDCMP(NULL) with care, especially if 
using one port with multiple windows. Be sure to ClearMenuStrip() any menus before closing a 
window, and do not free items such as dynamically allocated gadgets and menus while they are 
attached to a window. Do not reference an IntuiMessage's lAddress field as a structure pointer of 
any kind before determining it is a structure pointer (this depends on the Class of the IntuiMessage). 
If a crash or problem only occurs when opening a window after extended use of your program, check to 
make sure that your program is properly freeing up signals allocated indirectly by CreatePort(), 
OpenWindow() or ModifylDCMP(). 

Crashes - Workbench Only 

If you are crashing near the first DOS call, either your stack is too small or your startup code did not 
GetMsg() the WBStartup message from the process message port. If your program crashes during 
execution or during your exit procedure only when started from Workbench, and your startup opens no 
stdio window or NIL: file handles for WB programs, then make sure you are not writing anything to 
stdout (printf(), etc.) when started from WB (argc==0). See also "Crashes-After Exit". 

Device-related Problems 

Device-related problems may caused by: improperly initialized port or I/O request structures (use 
CreatePort() and CreateExtlO()); use of a too-small I/O request (see the device's <.h> files and 
Autodocs for information on the required type of I/O request); re-use of an I/O request before it has 
returned from the device (use the debugging tool IO_Torture\o catch this); failure to abort and wait for 
an outstanding device request before exiting; waiting on a signal/port/message allocated by a different 
task. 

Disk Icon Won't Go Away 

This occurs when a program leaves a Lock() on one or more of a disk's files or directories. A memory 



loss of exactly 24 bytes is usually Lock() which has not been UnLock()ed. 

DOS-related Problems 

In general, any dos. library function which fills in a structure for you (for example, Examine()), requires 
that the structure be longword aligned. In most cases, the only way to insure longword alignment in C is 
to dynamically allocate the structure. Unless documented otherwise, dos. library functions may only be 
called from a process, not from a task. Also note that a process's pr_MsgPort is intended for the 
exclusive use of dos. library. (The port may be used to receive a WBStartup message as long as the 
message is GetMsg()'d from the port before DOS is used. 

Fails only on 68020/30 

The following programming practices can cause this problem: using the upper bytes of addresses as 
flags; doing signed math on addresses; self-modifying code; using the MOVE SR assembler instruction 
(use Exec GetCC() instead); software delay loops; assumptions about the order in which asynchronous 
tasks will finish. The following differences in 68020/30 can cause problems: data and/or instruction 
caches must be flushed if data or code is changed by DMA or other non-processor modification; 
different exception stack frame; interrupt autovectors may be moved by VBR; 68020/30 CLR instruction 
does a single write access unlike the 68000 CLR instruction which does a separate read and write 
access (this might affect a read-triggered register in I/O space-use MOVE instead). 
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Fails only on 68000 

The following programming practices can be the cause of this problem: software delay loops; word or 
longword access of an odd address (illegal on the 68000). Note that this can occur under 2.0 if you 
reference lntuiMessage->IAddress as a structure pointer without first determining that the 
IntuiMessage's Class is defined as having a structure pointer in its lAddress; use of the assembler 
CLR instruction on a hardware register which is triggered by any access. The 68000 CLR instruction 
performs two accesses (read and write) while 68020/30 CLR does a single write access. Use MOVE 
instead; assumptions about the order in which asynchronous tasks will finish; use of compiler flags 
which have generated inline 68881/68882 math coprocessor instructions or 68020/30 specific code. 

Fails only on Older ROMs or Older WB 

This can be caused by asking for a library version higher than you need (Do not use the #define 
LIBRARY_VERSION when compiling!). Can also be caused by calling functions or using structures 
which do not exist in the older version of the operating system. Ask for the lowest version which 
provides the functions you need (usually 33), and exit gracefully and informatively if an OpenLibrary() 
fails (returns NULL). Or code conditionally to only use new functions and structures if the available 
Library's lib->Version supports them. 

Fails only on Newer ROMs or Newer WB 

This should not happen with proper programming. Possible causes include: running too close to your 
stack limits or the memory limits of a base machine (newer versions of the operating system may use 
slightly more stack in system calls, and usually use more free memory); using system functions 
improperly; not testing function return values; improper register or condition code handling in assembler 
code. Remember that result, if any, is returned in DO, and condition codes and D1/A0/A1 are undefined 
after a system call; using improperly initialized pointers; trashing memory; assuming something (such 
as a flag) is B if it is not A; failing to initialize formerly reserved structure fields to zero; violating Amiga 
programming guidelines (for example: depending on or poking private system structures, jumping into 
ROM, depending on undocumented or unsupported behaviors); failure to read the function Autodocs. 

See Appendix E, "Release 2 Compatibility", for more information on 2.0 compatibility problem areas. 

Fails only on Chip-RAM-Only Machines 

Caused by specifically asking for or requiring MEMF_FAST memory. If you don't need Chip RAM, ask 
for memory type 0L, or MEMF_CLEAR, or MEMF_PUBLIC|MEMF_CLEAR as applicable. If there is 
Fast memory available, you will be given Fast memory. If not, you will get Chip RAM. May also be 
caused by trackdisk-level loading of code or data over important system memory or structures which 
might reside in low Chip memory on a Chip-RAM-Only machine. 

Fails only on machines with Fast RAM 

Data and buffers which will be accessed directly by the custom chips must be in Chip RAM. This 
includes bitplanes (use OpenScreenQ or AllocRasterQ), audio samples, trackdisk buffers, and the 
graphic image data for sprites, pointers, bobs, images, gadgets, etc. Use compiler or linker flags to 



force Chip RAM loading of any initialized data needing to be in Chip RAM, or dynamically allocate Chip 
RAM and copy any initialization data there. 

Fails only with Enhanced Chips 

Usually caused by writing or reading addresses past the end of older custom chips, or writing 
something other than (zero) to bits which are undefined in older chip registers, or failing to mask out 
undefined bits when interpreting the value read from a chip register. Note that system copper lists are 
different under 2.0 when ECS chips are present. See "Fails only on Chip-RAM-Only Machines". 
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Fireworks 

A dazzling pyrotechnic video display is caused by trashing or freeing a copper list which is in use, or 
trashing the pointers to the copper list. If you aren't messing with copper lists, see above section called 
"Crashes and Memory Corruption". 

Graphics - Corrupted Images 

The bit data for graphic images such as sprites, pointers, bobs, and gadgets must be in Chip RAM. 
Check your compiler manual for directives or flags which will place your graphic image data in Chip 
RAM. Or dynamically allocate Chip RAM and copy them there. 

Hang - One Program Only 

Program hangs are generally caused by Wait()ing on the wrong signal bits, on the wrong port, on the 
wrong message, or on some other event that will never occur. This can occur if the event you are 
waiting on is not coming, or if one task tries to Wait(), WaitPort(), or WaitlO() on a signal, port, or 
window that was created by a different task. Both WaitlOQ and WaitPortQ can call Wait(), and you 
cannot Wait() on another task's signals. Hangs can also be caused by verify deadlocks. Be sure to 
turn off all Intuition verify messages (such as MENUVERIFY) before calling AutoRequestQ or doing 
disk access. 

Hang - Whole System 

This is generally caused by a DisableQ without a corresponding Enable(). It can also be caused by 
memory corruption, especially corruption of low memory. See "Crashes and Memory Corruption". 

Memory Loss 

First determine that your program is actually causing a memory loss. It is important to boot with a 
standard Workbench because a number of third party items such as some background utilities, shells, 
and network handlers dynamically allocate and free pieces of memory. Open a Shell for memory 
checking, and a Shell or Workbench drawer for starting your program. Arrange windows so that all are 
accessible, and so that no window rearrangement will be needed to run your program. 

In the Shell, type Avail FLUSH<RET> several times (2.0 option). This will flush all non-open 
disk-loaded fonts, devices, etc., from memory. Note the amount of free memory. Now without 
rearranging any windows, start your program and use all of your program features. Exit your program, 
wait a few seconds, then type Avail FLUSH<RET> several times. Note the amount of free memory. If 
this matches the first value you noted, your program is fine, and is not causing a memory loss. 

If memory was actually lost, and your program can be run from CLI or Workbench, then try the above 
procedure with both methods of starting your program. Note that under 2.0, there will be a slight 
permanent (until reboot) memory usage of about 672 bytes when the audio.device or narrator.device is 
first opened. See "Memory Loss-CLI Only" and "Memory Loss-WorkBench Only" if appropriate. If 
you lose memory from both WB and CLI, then check all of the open/alloc/get/create/lock type calls in 
your code, and make sure that there is a matching close/free/delete/unlock type call for each of them 
(note-there are a few system calls that have or require no corresponding free-check the Autodocs). 
Generally, the close/free/delete/unlock calls should be in opposite order of the allocations. 

If you are losing a fixed small amount of memory, look for a structure of that size in the Structure 
Offsets listing in the Amiga ROM Kernel Reference Manual: Includes and Autodocs. For example, a 
loss of exactly 24 bytes is probably a Lock() which has not been UnLockQed. If you are using 
ScrollRasterQ, be aware that ScrollRaster() left or right in a Superbitmap window with no TmpRas 
will lose memory under 1 .3 (workaround-attach a TmpRas). If you lose much more memory when 
started from Workbench, make sure your program is not using Exit(n). This would bypass startup code 
cleanups and prevent a Workbench-loaded program from being unloaded. Use exit(n) instead. 
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Memory Loss - CLI Only 

Make sure you are testing in a standard environment. Some third-party shells dynamically allocate 
history buffers, or cause other memory fluctuations. Also, if your program executes different code 
when started from CLI, check that code and its cleanup. And check your startup.asm if you wrote your 
own. 

Memory Loss - Ctrl-C Exit Only 

You have Amiga-specific resources opened or allocated and you have not disabled your compiler's 
automatic Ctrl-C handling (causing all of your program cleanups to be skipped). Disable the compiler's 
Ctrl-C handling and handle Ctrl-C (SIGBREAKF_CTRL_C) yourself. 

Memory Loss - During Execution 

A continuing memory loss during execution can be caused by failure to keep up with voluminous 
IDCMP messages such as MOUSEMOVE messages. Intuition cannot re-use IDCMP message blocks 
until you ReplyMsg() them. If your window's allotted message blocks are all in use, new sets will be 
allocated and not freed till the window is closed. Continuing memory losses can also be caused by a 
program loop containing an allocation-type call without a corresponding free. 

Memory Loss - Workbench Only 

Commonly, this is caused by a failure of your code to unload after you exit. Make sure that your code 
is being linked with a standard correct startup module, and do not use the Exit(n) function to exit your 
program. This function will bypass your startup code's cleanup, including its ReplyMsgQ of the 
WBStartup message (which would signal Workbench to unload your program from memory). You 
should exit via either exit(n) where n is a valid DOS error code such as RETURNOK 
(<dos/librariesh>), or via final "}" or return. Assembler programmers using startup code can JMP to 
_exit with a long return value on stack, or use the RTS instruction. 

Menu Problems 

A flickering menu is caused by leaving a pixel or more space between menu subitems when designing 
your menu. Crashing after browsing a menu (looking at menu without selecting any items) is caused 
by not properly handling MENUNULL select messages. Multiple selection not working is caused by not 
handling NextSelect properly. See the "Intuition Menus" chapter. 

Out-of-Sync Response to Input 

Caused by failing to handle all received signals or all possible messages after a Wait() or WaitPort() 
call. More than one event or message may have caused your program to awakened. Check the 
signals returned by Wait() and act on every one that is set. At ports which may have more than one 
message (for instance, a window's IDCMP port), you must handle the messages in a 
while(msg=GetMsg(...)) loop. 

Performance Loss in Other Processes 

This is often caused by a one program doing one or more of the following: busy waiting or polling; 
running at a higher priority; doing lengthy Forbid()s, Disable()s, or interrupts. 

Performance Loss - On A3000 

If your program has "Enforcer hits" (i.e., illegal references to memory caused by improperly initialized 
pointers), this will cause Bus Errors. The A3000 bus error handler contains a built-in delay to let the bus 
settle. If you have many enforcer hits, this could slow your program down substantially. 
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Trackdisk Data not Transferred 

Make sure your trackdisk buffers are in Chip RAM under 1 .3 and lower versions of the operating 
system. 

Windows - Borders Flicker after Resize 

Set the NOCAREREFESH flag. Even SMART_REFRESH windows may generate refresh events if 
there is a sizing gadget. If you don't have specific code to handle this, you must set the 
NOCAREREFRESH flag. If you do have refresh code, be sure to use the Begin/EndRefresh() calls. 
Failure to do one or the other will leave Intuition in an intermediate state, and slow down operation for 
all windows on the screen. 



Windows - Visual Problems 

Many visual problems in windows can be caused by improper font specification or improper setting of 
gadget flags. See the Appendix E on "Release 2 Compatibility" for detailed information on common 
problems. 

General Debugging Techniques 

Narrow the search 

Use methodical testing procedures, and debugging messages if necessary, to locate the problem area. 
Low level code can be debugged using KPrintF() serial (or dprintf() parallel) messages. Check the 
initial values, allocation, use, and freeing of all pointers and structures used in the problem area. 
Check that all of your system and internal function calls pass correct initialized arguments, and that all 
possible error returns are checked for and handled. 

Isolate the problem 

If errors cannot be found, simplify your code to the smallest possible example that still functions. Often 
you will find that this smallest example will not have the problem. If so, add back the other features of 
your code until the problem reappears, then debug that section. 

Use debugging tools 

A variety of debugging tools are available to help locate faulty code. Some of these are source level 
and other debuggers, crash interceptors, vital watchdog and memory invalidation tools like Enforcer 
and MungWall. 
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A Final Word about Testing 

Test your program with memory watchdog and invalidation tools on a wide variety of systems and configurations. 
Programs with coding errors may appear to work properly on one or more configurations, but may fail or cause 
fatal problems on another. Make sure that your code is tested on both a 68000 and a 68020/30, on machines 
with and without Fast RAM, and on machines with and without enhanced chips. Test all of your program 
functions on every machine. 

Test all error and abort code. A program with missing error checks or unsafe cleanup might work fine when all of 
the items it opens or allocates are available, but may fail fatally when an error or problem is encountered. Try 
your code with missing files, filenames with spaces, incorrect filenames, cancelled requesters, Ctrl-C, missing 
libraries or devices, low memory, missing hardware, etc. 

Test all of your text input functions with high-ASCII characters (such as the character produced by pressing Alt-F 
then "A"). Note that RAWKEY codes can be different keyboard characters on national keyboards (higher levels of 
keyboard input are automatically translated to the proper characters). If your program will be distributed 
internationally, support and take advantage of the additional screen lines available on a PAL system. Enhanced 
Agnus chip machines may be switched to be PAL or NTSC via motherboard jumper J102 in A2000s and jumper 
J200 in A3000s. Note that a base PAL machine will have less memory free due to the larger display size. 

Write good code. Test it. Then make it great. 
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Appendix E 

Release 2 Compatibility 

If you are developing new software or updating older software, you need to avoid compatibility traps. This 
comprehensive list of Release 2 compatibility problem areas can help you avoid and diagnose compatibility 
problems In addition, refer to the "General Amiga Development Guidelines" listed in Chapter 1 . 

General Compatibility Problem Areas 

The following improper Amiga programming practices are likely to fail on new ROMs or hardware. 

Requiring all free RAM. 

Overwriting memory allocations. With 32-bit addresses, a 1 -byte overwrite of a string array can wipe out 
the high byte of a pointer or stack return address. This bug could go unnoticed on a 24-bit address 
machine (e.g., A500) but crash the system or cause other problems on an A3000. 

Improper flags or garbage in system structures. A bit that means nothing under one OS may drastically 
change the behavior of a function in a newer version of the OS. Clear structures before using, and use 
correct flags. 

Misuse of function return values. Use function prototypes and read the Autodocs for the functions you 
are using. Some system functions return just success or failure, or nothing at all (void). In such 
cases, the value which the function happens to return must not be used except as it is documented. 

Depending on unsupported side effects or undocumented behavior. Be sure to read the Autodocs, 
include file comments and other documentation. 

Assuming current choices, configurations or initial values. If the current possibilities are A, B, or C, do 
not assume C if it isn't A or B. Check specifically for the choices currently implemented, and provide 
default behavior for unexpected values. 

Amiga debugging tools such as Enforcer, Mungwall and Scratch can find many program bugs that may affect 
compatibility. A program that is Enforcer/Mungwall/Scratch clean stands a much better chance of working well 
under current and future versions of the OS. 
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Release 2 Changes That Can Affect 
Compatibility 

There are several areas where Relase 2 OS changes and enhancements can cause compatibility problems for 
some software. 



Exec 



Do not jump to location $FC0002 - the start of the ROM under 1 .3 - as part of performing a system 
RESET. The 2.04 Kickstart ROM has a temporary compatibility hack called "Kickety-Split" which is a 
redirecting jump at $FC0002. This hack does not appear on the A3000 ROM and due to space 
considerations will not appear on future machines. 

Everything has moved. 

The Supervisor stack is not in the same place as it was under 1 .3. This has caused problems for some 
games that completely take over the Amiga. If your program goes into Supervisor mode, you must either 
respect allocated memory or provide your own Supervisor stack when taking over the machine. 



ExecBase is moved to expansion memory if possible. Before, ExecBase would only end up in one of 
two fixed locations. Now, ColdCapture may be called after expansion memory has been configured. 

Exception/Interrupt vectors may move. This means the 68010 and above Vector Base Register (VBR) 
may contain a non-zero value. Poking assumed low memory vector addresses may have no effect. You 
must read the VBR on 68010 and above to find the base. 

No longer tolerant of wild Forbid() counts. Under 1.3, sometimes this bug could go unnoticed. Make 
sure that all Forbid()s are matched with one and only one Permit() (and vice versa). 

When an Exec device gets an lORequest, it must validate io_Command. If the io_Command is or 
out of range, the device must return IOERR_NOCMD and take no other action. The filesystem now 
sends new commands and expects older devices to properly ignore them. 

A fix to task-switching in Release 2 allows a busy task to properly regain the processor after an interrupt 
until either its quantum (4 vertical blanks) is up or a higher priority task preempts it. This can 
dramatically change the behavior of multitask programs where one task busyloops while another 
same-priority task Wait()s. See "Task Switching" in the "Additional Information" section below. 

Expansion 

ExpansionBase is private - use FindConfigDev(). 

Memory from contiguous cards of the same memory type is automatically merged into one memory 
pool. 
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Romboot.library is gone. 

Audio.device cannot be OpenDevice()ed by a boot block program. See "Audio Device" below. 

Boot from other floppies (+5,-10,-20,-30) is possible. 

Undocumented system stack and register usage at Diag and Boot time have changed. 



Strap 



DOS 



DOS is now written in C and assembler, not BCPL. The BCPL compiler artifact which caused DO 
function results to also be in D1 is gone. System patches in Release 2 that return some DOS function 
results in both DO and D1 are not guaranteed to remain in the next release. Fix your programs! Use 
Scratch to find these problems in your code. 

DOS now has a real library base with normal LVO vectors. 

Stack usage has all changed (variables, direction). 

New packet and lock types. Make sure you are not passing stack garbage for the second argument to 
Lock(). 

Process structure is bigger. "Rolling your own" Process structure from a Task fails. Use dos. library 
System() or CreateNewProc(). 

Unless documented otherwise, you must be a process to call DOS functions. DOS function dependence 
on special process structures can change with OS revisions. 



Audio Device 



Now not initialized until used. This means low memory open failure is possible. Check your return 
values from OpenDevice(). This also means audio.device cannot be opened during 2.0 Strap unless 
lnitResident()ed first. If OpenDeviceQ of audio.device fails during strap, you must FindResidentQ/ 



lnitResident() audio.device, and then try OpenDevice() again. There will be a small memory loss (until 
reboot) generated by the first opener of audio.device or narrator. device (memory used in building of 
audio.device's base). 

Gameport Device 

Initial state of hardware lines may differ. 

Serial Device 

Clears io_Device on CloseDevice() (since 1 .3.2) 
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Timer Device 

The most common mistake programmers make with timer.device is to send off a particular timerequest 
before the previous use of that timerequest has completed. Use IO_Torture to catch this. 

IO_QUICK requests may be deferred and be replied as documented. 

VBLANK timer requests, as documented, now wait at least as long as the full number of VBIanks you 
asked for. Previously, a partial vertical blank could count towards your requested number. The new 
behavior is more correct and matches the docs, but it can cause VBIank requests to now take up to 1 
VBIank longer under 2.0 as compared to 1.3. For example, a 1/10 second request, may take 6-7 
Vblanks instead of 5-6 VBIanks, or about 15% longer. 

Trackdisk Device 

Private trackdisk structures have changed. See trackdisk.doc for a compatible REMCHANGEINT. 

Buffer is freeable, so low memory open failure is possible. 

Do not disable interrupts (any of them), then expect trackdisk to function while they are disabled. 

CIA Timers 

System use of CIA timers has changed. Don't assume how they're used. 

Don't depend on initial values of CIA registers. 

Don't mess with ClABase. Use cia. resource. 

If your code requires hardware level CIA timers, allocate the timers using cia.resource AddlCRVector()! 
This is very important. Operating system usage of the CIA timers has changed. The new 2.0 timer.device 
("Jumpy the Magic Timer Device") will try to jump to different CIAs so programs that properly allocate 
timers will have a better chance of getting what they want. If possible, be flexible and design your code 
to work with whatever timer you can successfully allocate. 

OS usage of INT6 is increasing. Do not totally take over INT6, and do not terminate the server chain if 
an interrupt is not for you. 

Other Hardware Issues 

Battery-backed clock is different on A3000. Use battclock.resource to access the real-time clock if 
battclock.resource can be opened. 

A 68030 hardware characteristic causes longword-aligned longword writes to allocate a valid entry in the 
data cache, even if the hardware area shouldn't be cached. This can cause problems for I/O registers 
and shared memory devices. To solve this: 1) don't do that 2) flush the cache or 3) use Enforcer Quiet. 
See the Motorola 68030 manual under the description of the Write Allocate bit (which must be set for the 
Amiga to run with the Data Cache). 
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Intuition 

Private IntuitionBase variables have moved/changed. Reading them is illegal. Writing them is both 
illegal and dangerous. 

Poking IntuitionBase MaxMouse variables is now a no-op, but stop poking when Intuition version is 
>35. 

If you are opening on the Workbench screen, be prepared to handle larger screens, new modes, new 
fonts, and overscan. Also see "Fonts" compatibility information. 

Screen TopEdge and LeftEdge may be negative. 

Left-Amiga-Select is used for dragging large screens. Do not use left-Amiga-key combinations for 
application command keys. The left-Amiga key is reserved for system use. 

For compatibility reasons, GetScreenDataQ lies if the Workbench screen is a mode only available after 
1 .3. It will try to return the most sensible mode that old OpenScreen() can open. This was necessary to 
prevent problems in applications that cloned the Workbench screen. To properly handle new modes, see 
LockPubScreen(), GetVPModelD(), and the SA_DisplaylD tag for OpenScreenTags(). 

Using combined RAWKEY and VANILLAKEY now gives VANILLAKEY messages for regular keys, and 
RAWKEY messages for special keys (fkeys, help, etc.) 

Moving a SIMPLE_REFRESH window does not necessarily cause a REFRESHWINDOW event because 
layers now preserves all the bits it can. 

Sizing a SIMPLE_REFRESH window will not clear it. 

MENUVERIFY/REQVERIFY/SIZEVERIFY can time out if you take too long to ReplyMsg(). 

Menu-key equivalents are ignored while string gadgets are active. 

You can't type control characters into string gadgets by default. Use Ctrl-Amiga-char to type them in or 
use IControl Prefs to change the default behavior. 

Width and Height parameters of AutoRequest() are ignored. 

New default colors, new gadget images. 

JAM1 rendering/text in border may be invisible gadgets over default colors. 

The cursor for string gadgets can no longer reside outside the cleared container area. If your gadget is 
32 pixels wide, with MaxChars of 4, all 32 pixels will be cleared, instead of just 24, as was true in 1 .3. 

Applications and requesters that fail to specify desired fonts will get the fonts the user sets up in Font 
Preferences in Release 2. These could be much larger, or proportional in some cases. Screen and 
window titlebars (and their gadgets) will be taller when accommodating a larger font. Applications which 
open on the Workbench screen must adapt to variable size titlebars. Any application which accepts 
system defaults for its screen, window, menu, Text or IntuiText fonts must adapt to different fonts and 
titlebar sizes. String gadgets whose height is too small for a font will revert to a smaller ROM font. 
There are now 2 different user-specifiable default system fonts which affect different Intuition features. 
This can lead to mismatches in mixed gadgets and text. See the "Intuition Screens" chapter. 
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Don't modify gadgets directly without first removing them from the gadget list, unless you are using a 
system function designed for that purpose, such as NewModifyProp() or SetGadgetAttrs(). 

Don't rely on NewModifyPropQ to fully refresh your prop gadget after you've changed values in the 
structure. NewModifyProp() will only correctly refresh changes which were passed to it as parameters. 
Use Remove/ Add/RefreshGList() for other kinds of changes. 



Custom screens must be of type CUSTOMSCREEN or PUBLICSCREEN. Other types are illegal. One 
application opens its screen with NewScreen.Type = (instead of CUSTOMSCREEN, OxOF). Then, 
when it opens its windows, it specifies NewWindow.Type of and NewWindow.Screen of NULL, 
instead of Type = CUSTOMSCREEN and Screen = (their screen). That happened to work before, but no 
longer. 

Referencing lntuiMessage->IAddress as a Gadget pointer on non-Gadget IDCMP messages, or as a 
Window pointer (rather than looking at the proper field lntuiMessage->IDCMPWindow) may now cause 
Enforcer hits or crashes. The lAddress field always used to contain a pointer of some type even for 
IDCMP events for which no lAddress value is documented. Now, for some IDCMP events, lAddress 
may contain a non-address, possibly an odd value that would crash a 68000 based system). 

Using Intuition flags in the wrong structure fields (for example, using ACTIVEWINDOW instead of 
ACTIVATE). To alleviate this problem, 2.0 has introduced new synonyms that are less confusing than 
the old ones. For example, IDCMP_ACTIVEWINDOW and WFLG_ACTIVATE. This particular example 
of confusion (there are several) was the nastiest, since IDCMP_ACTIVEWINDOW, when stuffed into 
NewWindow.Flags, corresponds numerically to WFLG_NW_EXTENDED, which informs Intuition that 
the NewWindow structure is immediately followed by a Tagltem, list which isn't there! Intuition does 
some validation on the tag-list pointer, in order to partially compensate. To make your compiler use 
the new synonyms only, add this line to your code before Intuition include files: #define 
INTUI_V36_NAMES_ONLY. 

Do not place spaces into the Stringlnfo->Buffer of a GACTLONGINT string gadget. Under 1 .3, this 
worked, but the 2.0 validation routine that checks for illegal keystrokes looks at the contents for illegal 
(i.e., non-numeric) characters, and if any are found assumes that the user typed an illegal keystroke. 
The user's only options may be shift-delete or Amiga-X. Use the correct justification instead. 

If you specify NULL for a font in an IntuiText, don't assume you'll get Topaz 8. Either explicitly supply the 
font you you need or be prepared to size accordingly. Otherwise, your rendering will be wrong, and the 
user will have to reset his Preferences just to make your software work right. 

Window borders are now drawn in the screen's DetailPen and BlockPen rather than the Window's 
pens. For best appearance, you should pass an SA_Pens array to OpenScreen(). This can be done in 
a backwards compatible manner with the ExtNewScreen structure and the NS_EXTENDED flag. 

The system now renders into the full width of window borders, although the widths themselves are 
unchanged. Window borders are filled upon activation and inactivation. 

Window border rendering has changed significantly for 2.0. Note that the border dimensions are 
unchanged from 1 .x (Look at Window->BorderLeft/Top/Right/Bottom if you don't believe us!). If your 
gadget intersects the border area, although it may have looked OK under 1 .3, a visual conflict may occur 
under 2.0. If Intuition notices a gadget which is substantially in the border but not declared as such, it 
treats it as though it were (this is called "bordersniffing"). Never rely on Intuition to sniff these out for you; 
always declare them explicitly (see the Gadget Activation flags GACT_RIGHTBORDER, etc.). See 
"Intuition Gadgets and Window Borders" in the "Additional Information" section below. 
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Preferences 

Some old struct Preferences fields are now ignored by SetPrefs (for example FontHeight). SetPrefs 
also stops listening to the pointer fields as soon as a new-style pointer is passed to Intuition (new-style 
pointers can be taller or deeper). 

Preferences ViewX/YOffset only applies to the default mode. You cannot use these fields to move the 
position of all modes. 

The Preferences LaceWB bit is not necessarily correct when Workbench is in a new display mode (akin 
to GetScreenData()). 

Workbench 

The Workbench GUI now has new screen sizes, screen top/left offsets, depths, modes, and fonts. 



Default Tool now searches paths. 

New Look (boxed) icons take more space. 

Do not use icons which have more 1 bits set in PlanePick than planes in the ImageData (one 
IFF-to-lcon utility does this). Such icons will appear trashed on deeper Workbenches. 

New Look colors have black and white swapped (as compared to 1 .3). 

The Workbench screen may not be open at startup-sequence time until some output occurs to the initial 
Shell window. This can break startup-sequence-started games that think they can steal WB's screen 
bitplanes. Do not steal the Workbench screen's bitplanes. (For compatibility, booting off pre-2.0 disks 
forces the initial screen open. This is not guaranteed to remain in the system.) Use startup code that can 
detach when RUN (such as cback.o) and use CloseWorkbenchQ to regain the screen's memory. In 
addition, see "Workbench and Startup" in the "Additional Information" section below. 

Layers 

Use NewLayerlnfo() to create, not FattenLayerlnfo(), ThinLayerlnfo(), lnitLayers(). 

Simple-refresh preserves all of the pixels it can. Sizing a SIMPLE_REFRESH window no longer clears 
the whole window. 

Speed of layer operations is different. Don't depend on layer operations to finish before or after other 
asynchronous actions. 

Graphics 

Do not rely on the order of Copper list instructions. The Release 2 MrgCopO function builds different 
Copper lists to that of 1.3, by including new registers in the list (e.g., MOVE xxxx,DIWHIGH). This 
changes the positions of the other instructions. We know of one game that 'assumes' the BPLxPTRs 
would be at a certain offset in the Copper list, and that is now broken on machines running 2.0 with the 
new Denise chip. 
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Graphics and layers functions which use the blitter generally return after starting the final blit. If you are 
mixing graphics rendering calls and processor access of the same memory, you must WaitBlit() before 
touching (or deallocating) the source or destination memory with the processor. For example, the Text() 
function is faster in Release 2, causing some programs to trash partial lines of text. 

ColorMap structure is bigger. Programs must use GetColorMapO to create one. 

Blitter rtns decide ascend/descend on 1st plane only. 

Changing the display mode of an existing screen or viewport while open is still not a supported 
operation. 

GfxBase DisplayFlags and row/cols may not match Workbench screen. 

Do not hardcode modulo values - use BitMap->BytesPerRow. 

If the graphics Autodocs say that you need a TmpRas of a certain size for some functions, then you 
must make that the minimum size. In some cases, before 2.0, you may have gotten away with using a 
smaller TmpRas with some functions (for example FloodQ). To be more robust, graphics now checks 
the TmpRas size and will fail the function call if the TmpRas is too small. 

ECS chips under 2.0 generate displays differently. The display window registers now control DMA. 

LoadRGB4() used to poke colors into the active copperlist with no protection against deallocation of that 
copperlist while it was being poked. Under 2.0, semaphore protection of the copperlist was added to 
LoadRGB4() which makes it totally incorrect and extremely dangerous to call LoadRGB4() during an 
interrupt. The general symptom of this problem is that a system deadlock can be caused by dragging 
one screen up and down while another is cycling. Color cycling should be performed from within a task, 



not an interrupt. In general, the only functions which may be safely called from within an interrupt are the 
small list of Exec functions documented in the "Exec Interrupts" chapter. 

Fonts 

Some font format changes (old format supported). 

Private format of .font files has changed (use FixFontsXo create). 

Default fonts may be larger, proportional. 

Topaz is now sans-serif. 

Any size font will be created via scaling as long as TextAttr.Flags FPF_DESIGNED bit is not set. If you 
were asking for an extreme size, like size 1 to get smallest available, or 999 to get largest available, you 
will get a big (or very very small) surprise now. 

Do not use -1 for TextAttr.Flags or Styles, nor as the flags for AvailFonts (one high bit now causes 
AvailFonts to return different structures). Only set what you know you want. A kludge has been 
added to the OS to protect applications which currently pass -1 for AvailFonts flags. 
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CLI/Shell 

Many more commands are now built-in (no longer in C:). This can break installation scripts that copy 
Cxommandname, and programs that try to Lock() or Open() C:commandname to check for the 
command's existence. 

The limit of 20 CLI processes is gone and the DOSBase CLI table has changed to accommodate this. 
Under V36 and higher, you should use new 2.0 functions rather than accessing the CLI table directly. 

Shell windows now have close gadgets. The EOF character is passed for the close gadget of a Shell. 
This is -1L with CON: getchar(), and the Close Gadget raw event ESC seq with RAW:. 

Shells now use the simple-refresh character-mapped console. 

By default, CON: now opens SIMPLEREFRESH windows using the V36/V37 console character 
mapped mode. Because of some differences between character mapped consoles, and 
SMART_REFRESH non-mapped consoles, this may cause incompatibilities with some applications. For 
example, the Amiga private sequences to set left/top offset, and set line/page length behave differently in 
character mapped console windows. The only known work-around is to recompile asking for a CON: (or 
RAW:) window using the SMART flag. 

Simple refresh/character mapped console windows now support highlighting and copying text with the 
mouse. This feature, as well as pasting text should be transparent to programs which use CON: for 
console input, and output. Pasted text will appear in your input stream as if the user had typed it. 

While CONCLIP (see s:startup-sequence) is running, programs may receive "<CSI>0 v" in their input 
stream indicating the user wants to paste text from the clipboard. This shouldn't cause any problems for 
programs which parse correctly (however we know that it does; the most common problems are 
outputting the sequence, or confusing it with another sequence like that for FKEY 1 which is "<CSI>0~"). 

The console. device now renders a ghosted cursor in inactive console windows (both 
SMART_REFRESH, and SIMPLE_REFRESH with character maps). Therefore, rendering over the 
console's cursor with graphics. library calls can trash the cursor; if you must do this, first turn off the 
cursor. 

Some degree of unofficial support has been put in for programs which use SMART_REFRESH console 
windows, and use graphics. library calls mixed with console.device sequences to scroll, draw text, clear, 
etc. This is not supported in SIMPLE_REFRESH windows with character maps, and is strongly 
discouraged in all cases. 

Closing an Intuition window before closing the attached console.device will now crash or hang the 



machine. 

Under 1 .2 and 1 .3, vacated portions of a console window (e.g., areas vacated because of a clear, or a 
scroll) were filled in with the character cell color. As of V36 this is no longer true, vacated areas are filled 
in with the global background color which can be set using the SGR sequence "<ESC>[>##m" where ## 
is a value between 0-7. In order to set the background color under Release 2, send the SGR to set 
background color, and a form feed to clear the screen. 

Note that SIMPLE_REFRESH character mapped consoles are immediately redrawn with the global 
background color when changed-this is not possible with SMART_REFRESH windows. 

Release 2 Compatibility 931 

Additonal Information 

Task Switching 

The 1.3 Kickstart contained two task switching bugs. After an interrupt, a task could lose the CPU to another 
equal priority task, even if the first task's time was not up. The second bug allowed a task whose time was up to 
hold on to the CPU either forever, or until a higher priority task was scheduled. Two busy-waiting tasks at high 
priority would never share the CPU. Because the input.device runs at priority 20, usually the effect of these bugs 
was masked out for low priority tasks. The ExecBase->Quantum field had little effect because of the bugs. 

For 2.0, a task runs until either its Quantum is up, or a higher priority task preempts it. When the Quantum time 
is up, the task will now lose the CPU. The Quantum was set to 16/60 second for 1.3, and 4/60 second for 2.0. 

In general, the 2.0 change makes the system more efficient by eliminating unnecessary task switches on 
interrupt-busy systems (for example, during serial input). However, the change has caused problems for some 
programs that use two tasks of equal priority, one busy-waiting and one Wait()ing on events such as serial input. 
Previously, each incoming serial character interrupt would cause task context switch allowing the event-handling 
task to run immediately. Under 2.0 the two tasks share the processor fairly. 

Intuition Gadgets and Window Borders 

If 2.0 Intuition finds a gadget whose hit area (Gadget LeftEdge/TopEdge/ Width/Height) is substantially inside the 
border, it will be treated as though it was declared in the border. This is called "bordersniffing". Gadgets declared 
as being in the border or detected by Intuition as being in the border are refreshed each time after the border is 
refreshed, and thus aren't clobbered. 

Noteworthy special cases: 

1 ) A gadget that has several pixels not in the border is not bordersniffed. An example would be an 1 8-pixel 
high gadget in the bottom border of a SIZEBBOTTOM window. About half the gadget will be clobbered 
by the border rendering. 

2) A gadget that is not substantially in the border but has imagery that extends into the border cannot be 
sniffed out by Intuition. 

3) A gadget that is substantially in the border but has imagery that extends into the main part of the window 
will be sniffed out as a border gadget, and this could change the refreshing results. A common trick to 
put imagery in a window is to put a 1x1 or 0x0 dummy gadget at window location (0,0) and attach the 
window imagery to it. To support this, Intuition will never bordersniff gadgets of size 1x1 or smaller. 

All these cases can be fixed by setting the appropriate GACT_xxxBORDER gadget Activation flag. 

4) In rare cases, buttons rendered with Border structures and JAM1 text may appear invisible under 
Release 2. 
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The height of the window's title bar is affected by the current font settings. See the discussion of "Screen 
Attributes" in the "Intuition Screens" chapter. To predict your window's titlebar height before you call 



OpenWindowQ: 

topborder = screen- >WBorTop + screen->Font->ta_YSize + 1 
The screen's font may not legally be changed after a screen is opened. 
Be sure the screen cannot go away on you. This is true if: 

1) You opened the screen yourself. 

2) You currently have a window open on the screen. 

3) You currently hold a lock on this screen (see LockPubScreen()). 

IntuiText rendered into a window (either through PrintlTextQ or as a gadget's GadgetText) defaults to the 
Window RastPort font, but can be overridden using its ITextFont field. Text rendered with the Text() function 
appears in the Window RastPort font. 

The Window's RPort's font shown above is the initial font that Intuition sets for you in your window's RastPort. It 
is legal to change that subsequently with SetFont(). 

Workbench and Startup 

Under 1 .3, the Workbench Screen and initial Shell (CLI) opened before the first line in s:startup-sequence. Some 
naughty programmers, in an attempt to recover memory, would search for the bitplane pointers and appropriate 
the memory for their own use. This behavior is unsafe. 

By default 2.0 opens the initial CLI on the first _output_ from the s:startup-sequence. This allows screen modes 
and other parameters to be set before the user sees the screen. However, this broke so many programs that we 
put in the "silent-startup" hack. A disk installed with 1 .3 install opens the screen as before. A disk installed under 
2.0 opens silently. Never steal the Workbench bitplanes. You don't know where they are, how big they are, what 
format they may be in, or even if they are allocated. Recovering the memory is a bit tricky. 

Under 2.0, simply avoid any output from your s:startup-sequence. If your program opens a screen it will be the 
first screen the user ever sees. Note that if ENDCLI is ever hit, the screen will pop open. 

Under 1.3, after ENDCLI, use CloseWorkbenchQ to close the screen. This also works under 2.0. Loop on 
CloseWorkbenchQ with a delay between loops. Continue looping until CloseWorkbench() succeeds or too much 
time has passed. Note that a new program called EndRun is available for starting non-returning programs from 
the startup-sequence. EndRun will reduce memory fragmentation and will close Workbench if it is open. 
EndRun. Izh will be available in Commodore's Amiga listings area on BIX. 
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Index 



1.3 



2.0 



compatibility, 18 



compatibility, 923, 
differences, 923 
32-bit math, 878 

example, 879, 
function reference, 883, 
functions, 878 



3D Look 



window title bar, 1 07, 
windows, 79 



4703,517 
68000 

crash, 916 
68020,917 
68030,917 
68040 

crash, 916 
68881 , 845, 853 
68882, 853 
680x0 

68040, 479 

Cache, 479 

caches, 477 

CopyBack mode, 479 

development guidelines, 15 

Exceptions, 473 

Floating Point Unit, 477 

FPU, 477 

GetCCQ, 478 

Interrupt stack, 477 

ISP, 477 

Master stack, 477 

MSP, 477 

Paged Memory Management Unit, 477 

PMMU, 477 

programming guidelines, 17 

Register usage conventions, 6 

self-modifying code, 478 

SetSRQ, 478 

SSP, 477 

Stack, 477 

Supervisor Mode, 477 

Supervisor stack, 477 

User stack, 477 

USP, 477 
AbortlOQ, 451 
Accessing a Device, 446 
Activate 

window on open, 110 
ActivateCxObJO, 731 
ActivateGadget(), 150, 166, 321 
ActivateWindow(), 91 , 115 
active gadget, 323 
Active Window, 

input focus, 248 

Menu verify, 186 

notification, 82, 91 
AddAnimOb(), 659, 668 
AddBob(), 641,668 
AddBootNodef), 759, 776 
AddClass(),312, 330 
AddDosNodef), 759, 776 
AddGadgetO, 166 
AddGListO, 122, 129, 166 
ADDHEAD, 498 
AddHeadf), 492, 498, 520 
Add I Events)), 749 
AddlntServer(), 525 
AddLibrary(), 443 
AddPortQ, 501,511 
AddPublicSemaphoreO, 51 1 
Address error, 474 
AddSemaphoreO, 511, 515 
ADDTAIL, 498 
AddTail(), 492, 498, 520 
AddTaskQ, 466, 480 



AddTOFf), 888 
AddVSprite(), 627, 668 
Adjust 

window size, 1 1 1 
AFFJ3ISK, 689 
AFFJvlEMORY, 689 
AFF_SCALED, 689 
AFF_TAGGED, 689 
afp(), 888 
Agnus, 1 1 
Alert, 220 

application, 220 

DEADEND_ALERT, 220 

DisplayAlertO, 221 

positioning, 220 

RECOVERY_ALERT, 220 

screen mode ID, 220 

software error, 474 

system, 220 
Alert(), 520 

AllocAslRequestO, 416 
AllocAslRequestTags(), 421 
Allocate)), 462 
Allocating memory, 455 
AllocEntryO, 459, 461 , 462 
AlloclFFO, 344, 810 
AllocLocalltemO, 790, 810 
AllocMemO, 274, 284, 288, 430, 455, 457, 466 
AllocRaster(), 98, 552, 610, 

allocating memory, 560 
AllocRememberO, 283, 284, 284, 285, 288, 289 
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AllocSignalO, 254, 476, 482, 485 
AllocTrapO, 476, 480 
AllocVecQ, 430 
Alt Key, 282 

with right Amiga key, 176 
Alternate 



Alt key, 282, 

window size zoom, 108 



Amiga 



custom chips, 11 

development guidelines, 13 

memory architecture, 8 

operating system versions, 10 

Register usage conventions, 6 
Amiga Key Glyph 

menus, 184 
Amiga keys 

as command keys, 282, 

Workbench shortcuts, 281 
Amiga.lib, 438, 885, 

stub, 438 
AndRectRegion(), 722 
AndRegionRegion(), 722 
ANFRACSIZE, 661 
Animate(), 660, 668 
Animation 

AddBob(), 641 

Animate)), 660 

AnimComp 

animation concepts, 652 
AnimComp flags, 659 
custom animation routine, 660 
ring motion control, 654 
sequenced drawing, 654 
sequencing components, 656 
sequencing within components, 655 
setting animation timing, 655 
setting component position, 655 
setting up ring motion control, 659 
setting up simple motion control, 658 
simple motion control, 654 
specifying components, 655 

AnimOb, 656 

adding an AnimOb, 659 
custom animation routine, 660 
moving the objects, 660 
setting AnimOb position, 658 
special numbering system, 661 
the AnimKey, 659 



typical function call sequence, 660 



Bob 



attaching a Bob to a VSprite, 635 
behavior for unselected bitplanes, 639 
Bob flags, 636 
changing a Bob, 642 
double-buffering, 645 
ImageShadow, 635 
setting bitplanes, 639 
setting collision detection, 639 
setting color, 638 
setting depth, 638 
setting image, 637 
setting rendering priority, 640 
setting rendering restrictions, 640 
setting shadow mask, 638 
setting shape, 637 
setting size, 637 

struct VSprite differences for Bobs, 634 
system selected rendering priorities, 640 
using Bobs, 634 
VSprite flags for Bobs, 634 
collision detection, 646 
adding user-defined data to GELs, 651 
AUserStuff, 651 

BorderLine for faster detection, 648 
boundary collision flags, 650 
building the collision handler table, 646 
BUserStuff, 651 

initializing collision detection, 646 
parameters to user-defined routines, 650, 650 
processing of multiple collisions, 650 
selective collision detection, 649 
sensitive areas, 647 
setting the collision mask, 647 
specifying collision boundaries, 650 
UserExt, 651 
VUserStuff, 651 
DoCollision(), 646 
DrawGList(), 642 
Examples 

complete bobs example, 642 
InitMasksO, 648 
introduction, 613 
RemBobO, 641 
RemlBobO, 641 
SetCollision(), 647 
SortGList(), 642 
struct Bob, 635 
struct CollTable, 646 
struct DBufPacket, 645 
AnimComp structure, 652 
ANIMHALF, 661 
AnimOb structure, 652 
ANSI Codes, 90 
AOIPen 

in filling, 584, 
in RastPort, 584 
Area pattern, 585 
AreaCircle(), 590, 611 
AreaDraw(),611 

adding a vertex, 589, 
in area fill, 582 
AreaEllipsef), 590, 611 
AreaEndQ, 611 

drawing and filling shapes, 590, 
in area fill, 582 
Arealnfo pointer, 582 
AreaMove(), 611 

beginning a polygon, 589, 
in area fill, 582 
ARexx, 21 , 888 
ArgArrayDonef), 735, 888 
ArgArraylnitO, 735, 888 
Arglnt(), 735, 888 
ArgString(), 735, 888 
arnd(), 888 

AskKeyMapDefault(), 812 
AskSoftStyle(), 675 
ASL, 415 

AllocAslRequest(), 416 
AllocAslRequestTags(), 421 
AslRequestQ, 416 



AslRequestTags(), 421 

Basic ASL Requester Tags, 41 7 
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calling custom functions, 425 

creating a file requester, 41 6 

custom function parameters, 426 

custom screens, 421 

directory requester, 422 

Examples 

custom hook function, 426 

file requester with multiple selection, 41 9 

file requester with pattern matching, 419 

font requester, 424 

simple file requester, 41 7 

font requester, 422 

font requester flags, 423 

Font Requester Tags, 423 

FreeAslRequest(),416 

function reference, 428 

hook function flags, 425 

save requester, 421 

special flags, 419 

struct FileRequester, 416 

struct FontRequester, 422 
ASL Library, 20 
asl. library - see ASL 
AslRequest(),416 
AslRequestTags(), 421 
ASL_BackPen, 423 
ASLCancelText, 417 
ASL_Dir, 417 
ASL_File, 417 
ASL_FontFlags, 423 
ASL_FontHeight, 423 
ASL_FontName, 423 
ASL_FontStyles, 423 
ASL_FrontPen, 423 
ASL_FuncFlags, 419 
ASLJHail, 417 
ASLJHeight, 417 
ASLJHookfunc, 425 
ASLJ_eftEdge, 417 
ASLJvlaxHeight, 423 
ASLJvlinHeight, 423 
ASLJvlodeList, 423 
ASL_OKText, 41 7 
ASLJTopEdge, 417 
ASLJ/Vidth, 41 7 
Aspect Ratio, 20 
AttachCxObJO, 737 
AttemptSemaphoreO, 513, 513, 515 
attribute 

Boopsi, 293 

attribute/value pairs, 294 

mapping, 299 

see ICA MAP 
attributes 

OM_GET, 311 

setting, 309 
AUD0-AUD3 Interrupts, 519 
Audio device, 925 
AUserStuff, 651 
Autoboot, 760 
AUTOCONFIG 

hardware manufacturer number, 756, 

see Expansion, AUTOCONFIG 
AUTOKNOB, 147 

AutoRequestO, 97, 1 88, 201 , 21 1 , 21 5, 21 6, 222 
AUTOSCROLL, 49 
Autovector Address, 518 
AvailFontsO, 688 
AvailFonts structure, 688 
AvailFontsHeader structure, 688 
AvailMemQ, 459 
Backdrop 

advantages over screen, 92 

attribute, 110 

hide screen title, 92 

window depth arrangement, 92 

window system gadgets, 92 

window type, 92, 92 



Backdrop Layer, 706 
Background pen, 584 
BACKGROUNDPEN, 58, 141 
Backup 

of display areas, 705 
Beam synchronization, 600 
BeginlOQ, 448, 449, 520, 886 

BeginRefresh(), 95, 97, 97, 110, 115, 128,244,261,721 
BeginUpdateO, 128, 711,721 
Behind 

open screen, 49 
BehindLayerf), 708, 711 
Bell 

visible, 75 
BgPen- 

n RastPort, 584 
BindDhvers, 758 
BitMap, 64 

address, 552 

and Intuition graphics, 223, 224 

custom for screen, 48 

in requester, 205 

initializing, 582 

larger than layer, 706 

menu items, 169 

requester, 206 

scaling, 598 

software clipping, 590 

with write mask, 583 
BitMap Structure, 39, 98, 1 1 1 , 21 3, 226, 703, 705, 706 

in dual-playfield display, 579 

in super bitmap layers, 706 

preparing, 552 
BitMapScalef), 598, 612 
BitPlane 

and Image data, 227 

color of unused, 230 

extracting a rectangle from, 595 

in dual-playfield display, 578 

in Image structure, 225 

picking, 230 
BLIT Interrupts, 519 
Blitter 

in Bob animation, 615 

in copying data, 599 

minterm, 597 

programming, 600 

VBEAM counter, 601 
Block 

graphics with layers, 708 
Block Input, 203 
Block Pen, 106 
BLOCKPEN, 57 
BltBitMapf), 596, 597, 612 
BltBitMapRastPort(), 596, 597, 612 
BltClear(), 592, 612 
BltMaskBitMapRastPort(), 596, 598, 612 
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bltnode structure, 600 

creating, 601 , 

linking blitter requests, 600 
BltPattern(), 594, 612 
BltTemplateO, 595, 596, 612 
BNDRYOFF(), 590, 611 
Bob structure, 635 
Bobs 

introduction, 613, 

simple definition, 615 
Boollnfo structure, 139 
BOOLMASK, 139 
Boopsi, 291 - see also Appendix B: Boopsi Class Reference 

AddClassQ, 312 

attribute, 293 

attributes 

OM_GET, 31 1 , 
setting, 295, 296, 309 

Boopsi and Tags, 294 

Building on Existing Public Classes, 306 

Building Rkmmodelclass, 306 

buttonglclass, 315 

Callback Hooks, 312 



caveats 



message, 293, 
struct Gadgetlnfo, 316 



class, 292 

creating, 305 
custom, 305 
private, 293 
public, 293 

class reference, 891 

Creating an Object, 294 

dispatcher, 305 

Dispatcher Hook, 312 

DisposeObject(), 295 

Disposing of an Object, 295 

DoMethod(), 302 

DoMethodAQ, 302 

DoSuperMethod(),310 

DoSuperMethodAQ, 308, 310 

Example 

custom gadget class, 323 
custom model subclass, 312 
Talk2boopsi.c, 299 

function descriptions, 330 

gadget, 291 

ActivateGadgetO, 321 
active gadget, 323 
GFLG_DISABLED, 321 
GMRJvlEACTIVE, 321 
GMRJMEXTACTIVE, 321 
GMR_NOREUSE, 321 
GMR_PREVACTIVE, 321 
GMR_REUSE, 321 
GM_GOINACTIVE, 322 
handling input, 320 
implemention of, 318 
Methods, 318 
ObtainGIRPort(), 323 
ReleaseGIRPortf), 323 
RemoveGListO, 322 
rendering a gadget, 319 

gadgetclass, 292, 297 

buttongclass, 297 
frbuttonclass, 298 
groupgclass, 297 
propgclass, 297 
strgclass, 297 

GA_RelVerify, 301 

GetAttr(), 296, 301 

getting attributes, 296 

GFLG_RELVERIFY, 301 

GMRJ3ADGETHIT, 320 

GM_GOACTIVE, 318, 320 

GM_GOINACTIVE, 318 

GMJHANDLEINPUT, 318, 321 

GMJHITTEST, 318, 320 

GM_RENDER, 318, 319 

GREDRAW_REDRAW, 319 

GREDRAW_TOGGLE, 319 

GREDRAWJJPDATE, 319 

handling input, 320 

ICA_MAP 

Boopsi gadgets, 299, 
icclass, 302 

ICA_TARGET, 309 

Boopsi gadgets, 298, 302, 
icclass, 302 

icclass, 292, 297, 302 

ICSPECIAL_CODE 

Boopsi gadgets, 302 

IDCMPJ3ADGETUP, 301 

IDCMPJDCMPUPDATE 

Boopsi gadgets, 302 
imageclass, 292, 297 
fillrectclass, 297 
frameiclass, 297 
itexticlass, 297 
sysiclass, 297 

Images, 291 

inheritance, 293, 306, 31 1 

input events, 321 

instance, 292 

instance data, 293, 308 

initializing, 308 



Border 



INST_DATA() macro, 309 

Intuition public classes, 297 

MakeClassO, 311 

Making Objects Talk to Each Other, 298 

Making Objects Talk to the Application, 301 

message, 293 

final, 309, 

interim, 309 
methods, 293 
modelclass, 302 
Msg, 307 
NewObjectO, 295 
NewObjectAQ, 294 
object, 292 
ObtainGIRPort(),319 
obtaining gadget RastPort, 319 
OM_ADDMEMBER, 302, 307 
OM_ADDTAIL, 307 
OMJ3ISPOSE, 296, 307 
OMJ3ET, 296, 307, 311 
OM_NEW, 296, 307, 308 
OM_NOTIFY, 307, 309 
OM_REMMEMBER, 307 
OM_REMOVE, 307 
OM_SET, 296, 305, 307, 309 

Boopsi gadgets, 298 
OMJJPDATE, 307, 309 

Boopsi gadgets, 298 
OOP Overview, 292 
OPUFJNTERIM, 309 
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RemoveClass(),312 

rootclass, 292, 297 

SetAttrsO, 295 

SetGadgetAttrsO, 295, 305 

setting attributes, 295 

struct Gadgetlnfo, 316, 318 

struct gpGolnactive, 322 

struct gpHitTest, 320 

struct gplnput, 320 

struct gpRender, 319 

struct Hook, 312 

struct InputEvent, 321 

struct Msg, 303 

struct opGet, 31 1 

struct opMember, 303 

struct opSet, 305, 308 

struct opUpdate, 309 

subclass, 292 

superclass, 292 

typedef Class, 305 

user input, 321 

White Boxes-The Transparent Base Classes, 316 

Writing a Dispatcher, 307 



calculating window border size, 89 

containing size gadget, 109 

dimensions (from window), 105 

gadgets in, 88 

graphics offsets, 89 

in requester, 204 

in requester gadgets, 206 

position, 224 

rast port, 1 05 

size precalculation, 41 

using, 234 

window 88-89 
Border structure, 123, 212, 223, 224, 224, 234-235, 235, 238 

BackPen, 234 

Count, 234 

data organization, 237 

definition, 234 

DrawMode, 234 

FrontPen, 234, 237 

LeftEdge, 234, 235, 238, 238 

NextBorder, 235, 238 

TopEdge, 234, 235, 238, 238 

XY 234, 235, 237-238 
BORDERHIT, 648 
Borderless 

advantages over screen, 93 



attribute, 110 

window type, 92, 93 

with backdrop, 93 
bottommost 

in Gelslnfo, 624 
Box 

menu item, 180 
B-Pen see BgPen 
Break key, 432 
Broadcast 

IDCMP events, 248 
BuildEasyRequestO, 217, 218-219, 222 
BuildEasyRequestArgs(), 219, 222 
BuildSysRequestf), 218, 222 
Bus error, 474 
BUserStuff, 651 
Busy Pointer, 274 
buttongclass, 297 
buttonglclass, 315 
CacheClearE(), 479 
CacheClearUO, 479 
CachePostDMA(), 479 
CachePreDMAf), 479 
Caches, 477 
Callback Hooks, 312 
CallHookQ, 890 
CallHookA(), 890 
Cancel 

in requester, 203 
Cause(), 520, 527 
Caveats 



Boopsi 



Gadgets 



GadTools 



message, 293, 
struct Gadgetlnfo, 316 

do not share knob imagery, 143 
do not use image lists for knobs, 143 
GimmeZeroZero window border, 136 
imagery and the selection box, 124 
mouse tracking with boolean gadgets, 136 

GadTools enforces Intuition limits, 375 
GADTOOL_TYPE bit, 401 
GT_SetGadgetAttrs() & GT_BeginRefresh(), 386 
PLACETEXT with GENERIC_KIND gadgets, 398 
post-processing, 368 
preserve bits set by CreatsGadgetf), 398 
refreshing the display, 382 
restrictions on gadgets, 41 1 
side effects, 412 



keymap 



key numbers over hex 67, 818 

preferences 

printer device, 334 

Text 

don't assume Topaz-8, 672 
CBERR_DUO, 731 
CBERR_OK, 731 
CBERR_SYSERR, 731 
CBERR_VERSION, 731 
CBump(),603, 612 
CDB_CONFIGME, 756 
CDB_SHUTUP, 756 
CDF_CONFIGME, 756 
CDF_SHUTUP, 756 
CD_ASKKEYMAP, 813 
CD_SETKEYMAP, 813 
CENDQ, 603, 612 
ChangeSprite(), 619, 668 
ChangeWindowBox(), 112, 115 
Character Mapped 

applications, 249 
CHECKED, 175, 181, 182, 182, 191 
ChecklOf), 450 

CHECKIT, 181-182, 182, 182, 191 
Checkmark 

custom (for menus), 107 

menu items, 181 

menus, 170 

mutual exclude, 182 

positioning, 182 

size, 182 

tracking, 182, 185 



CheckRexxMsgQ, 888 
CHECKWIDTH, 182 
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chip, 227 

Chip Memory, 1 1 , 288, 431 , 456 

Image data, 227 

in Border structure, 237 

sprite data, 274 

with Image data, 226 
CHK instruction, 474 
CIA, 926 

CINIT(), 602, 612 
Class, 292 

custom, 305, 

dispatcher, 305, 

MakeClassO, 311 
Class typedef, 305 
ClearCxObjError(), 742 
ClearDMRequestf), 210, 222 
ClearEOL(), 675 

ClearMenuStripQ, 1 1 1 , 1 71 , 1 75, 1 86, 200 
ClearPointer(), 114, 115, 274, 282 
ClearRectRegion(), 722 
ClearRegion(), 722 
ClearScreenQ, 675 
Clicking 

definition, 265 
ClipBlitO, 596, 598,612 
Clipping 

in area fill, 590 

in filling, 590 

in line drawing, 588 

requester, 204 
Clipping Graphics 

layers, 719 
Clipping Rectangles 

in layers, 704, 711,712, 719 

modifying regions, 722 
Clipping region 

in VSprites with GELGONE, 624 
Close 

enable gadget, 109 
Close Gadget 

window, 78, 82 
Close vector, 437 
CloselFF(), 344,810 
CloseLibrary(), 436 
CloseMonitor(), 568, 611 
CloseScreen(), 42, 53, 76 
CloseWindowQ, 82, 109, 115, 175 
CloseWindowSafelyO, 254, 255 
CloseWorkBenchQ, 52, 76 
Closing A Device, 450 

outstanding lORequests, 451 
CMOVE(), 603, 612 
CoerceMethod(), 330, 890 
CoerceMethodA(), 330, 890 
Coercion, 565 

screens, 66 
COERR_BADFILTER, 742 
COERR_BADTYPE, 742 
COERRJSNULL, 742 
COERR_NUI_LATTACH, 742 
CollectionChunk(), 785, 810 
Collectionltem(), 785 
CollTable structure, 646 
Color 

ColorMap structure, 553 

flickering, 633 

full screen palette, 47, 59 

in Border structure, 237 

in dual playfield mode, 545 

in flood fill, 590 

in hold-and-modify mode, 580-581 

in the Image structure, 227-228 

Intuition text, 242 

of individual pixel, 587 

Playfield and VSprites, 633 

relationship to bitplanes, 539 

relationship to depth of BitMap, 543 

Simple Sprites, 618 



single-color raster, 593 

specifying for screen, 47, 65 

sprites, 546 

transparency, 626 

VSprite, 626 

with plane pick, 230 

with PlaneOnOff, 230 
Color mode - 

n Flood() fill, 591 
Color Registers, 228 
ColorFontColors structure, 698 
ColorMap, 64, 553 
ColorSpec Structure, 47 

Colorlndex, 47 
ColorTextFont structure, 697 
Command Key, 184 

menu item, 190, 

menus, 170, 

symbol position, 185 
Commodities 

ActivateCxObj(), 731 

AddlEventsQ, 749 

ArgArrayDonef), 735 

ArgArraylnit(), 735 

Arglnt(), 735 

ArgString(), 735 

AttachCxObJO, 737 

ClearCxObjError(), 742 

connecting CxObjects, 737 

controller commands, 734 

controlling CxMessages, 746 

custom CxObject function arguments, 744 

custom CxObjects, 744 

custom input handlers, 727 

CxBroker(), 730 

CxCustom(), 744 

CxDebugO, 745 

CxFilter(), 736 

CxMessage, 729, 731 

CxMessage types, 731 

CxMsgDataf), 731 

CxMsglDf), 731 

CxMsgType(), 731 

CxObject, 729, 729-730 
broker, 730 

CxObject error values, 742 

CxObject errors, 742 

CxObjErrorf), 742 

CxSender(), 741 

CxSignal(), 743 

CxTranslatef), 741 

debug CxObjects, 745 

DeleteCxObj(), 734 

DeleteCxObjAIIO, 734 

DisposeCxMsgO, 746 

DivertCxMsgO, 746 
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EnqueueCxObjQ, 737 
error codes, 731 
event classes, 736 
Examples 

custom CxObject for swapping mouse buttons, 744 

hotkey pop-up shell commodity, 750 

input description strings, 737 

monitoring user inactivity, 747 

opening a broker commodity, 731 

simple hot key commodity, 738 
filtering events, 736 
FreelEventsO, 749 
function reference, 753 
generating new input events, 749 
input description strings, 736 
InputXpression.ixQualSame bits, 745 
InsertCxObJO, 737 
lnvertString(), 749 
IX structure, 745 
IX.ix_QualSame bits, 745 
ParselXQ, 746 
RemoveCxObj(), 737 
requiring uniqueness, 743 
RouteCxMsgQ, 746 



sender CxObjects, 741 

SetCxObjPri(), 737 

SetFilter(), 746 

SetFilterlX(), 746 

SetTranslate(), 742 

shutting down a commodity, 734 

signal CxObjects, 743 

struct InputXpression, 745 

struct NewBroker, 730 

tool types, 734 

translate CxObjects, 741 

uniqueness, 743 

using the IX structure, 746 
commodities. library - see Commodities 
COMMSEQ, 184, 190, 191 
COMMWIDTH, 185 
Compatibility 

international, 922 

open screen, 43 

open window, 80 

with 2.0, 923 
Compatibility notes, 923 

Compatibility problems, 917, 918, 918, 918, 919, 918, 918 
COMPLEMENT, 234, 237, 240, 243, 585 
CON: 

on custom screen, 20 
ConfigDev structure, 756 
Console 

handler (CON:), 20 
Console Device, 90, 246 

input/output, 248 
console.device 

CD_ASKKEYMAP, 813, 

CD_SETKEYMAP, 813 
ContextNode structure, 789 
Control (Ctrl) key, 282 
Control-C, 432 
Coordinates 

in Border structure, 237 
COPER, 519, 525 
COPER Interrupts, 519, 525 
Copper, 65 

changing colors, 553 

display instructions, 555 

in drawing VSprites, 633 

in interlaced displays, 579 

MakeVPortQ, 560 

MrgCopf), 555 

programming, 602 
Copper list, 603 

deallocation, 560 

merge screens, 66 

update screen's, 66 

user, 602 

clipping of, 603 
Coprocessor 

copper list, 65 
Copy 

rectangles, 720, 721 
Copying 

data, 597, 

rectangles, 597 
CopyMem(), 288, 459 
CopyMemQuickO, 459 
CopySBitMapQ, 98 
CPU Priority Level, 519 
Crash, 91 6 

68000,916, 

68040,916 
Crashing 

with drawing routines, 588, 

with fill routines, 590 
CreateBehindLayer(), 710, 710 
CreateContextf), 399, 413 
CreateExtlOO, 886 
CreateGadgetO, 380, 413 
CreateGadgetA(), 413 
CreateMenusO, 374, 413 
CreateMenusAQ, 374, 413 
CreateMsgPortO, 501 
CreateNewProc(), 20 
CreatePortf), 254, 501,887 
CreateStdlOf), 887 



CreateTask(), 467, 887 
CreateUpfrontLayer(), 710, 710, 712 
Critical section, 470 
Ctrl, 282 

CT_COLORFONT, 697 
CTJ3REYFONT, 697 
CurrentBinding structure, 759 
CurrentChunk(), 344, 789, 810 
CurrentTime(), 288, 289 
Custom 

screen window on, 82, 107 
Custom Chips, 1 1 
Custom Gadgets - see Boopsi 
CUSTOMBITMAP, 48 
CUSTOMSCREEN, 107 
CWAIT(), 602, 612 
CxBroker(), 730 
CXCMD_APPEAR, 734 
CXCMDJ3ISABLE, 734 
CXCMD_DISAPPEAR, 734 
CXCMD_ENABLE, 734 
CXCMD_KILL, 734 
CxCustom(), 744, 889 
CxDebug(), 745, 889 
CxFilter(), 736, 889 
CxMsgDataf), 731 
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CxMsglDQ, 731 
CxMsgType(), 731 
CXM_COMMAND, 731 
CXMJEVENT, 731 
CxObjErrorQ, 742 
CxSenderQ, 741,889 
CxSignalO, 743, 889 
CxTranslateO, 741 , 889 
CX_POPKEY, 734 
CX_POPUP, 734 
CX_PRIORITY, 734 
DAC_BINDTIME, 761 
DAC_BOOTTIME, 761 
DAC_BUSWIDTH, 761 
DAC_BYTEWIDE, 761 
DAC_CONFIGTIME, 761 
DAC_NEVER, 761 
DAC_NIBBLEWIDE, 761 
DACJA/ORDWIDE, 761 
Damage List 

in layers, 711, 719 
Dates, 881 

example, 882 

function reference, 884 

functions, 881 

structure, 881 
dbf(), 888 

DBufPacket structure, 645 
DEADEND_ALERT, 220, 221 
DeadKeyConvert(), 262, 277 
Deadlock 

verify messages, 219, 250, 263 

with layers, 708 

with menus, 188 

with menuverify, 216 
Deallocate)), 462 
Deallocate 

region, 720 
Deallocation 

memory, 455 
Debugging, 921 
Debug. lib, 886 
Default 

pens in screen, 55, 

public screen, 59 
Default Public Screen, 52 
DeleteCxObj(), 734 
DeleteCxObjAIIO, 734 
DeleteDiskObject(), 353 
DeleteExtlOO, 886 
DeleteLayerj), 710 
DeleteMsgPort(), 502 
DeletePort(), 254, 502, 887 
DeleteStdlOQ, 887 



DeleteTask(), 467, 887 
Delta Move 

mouse coordinates, 268 
Denise, 1 1 
Depth 

BitMap, 543, 

in VSprite structure, 625 
Depth Gadget 

enable gadget, 109 

keyboard qualifier, 78 

screens, 74 

window, 78 
Detail Pen, 106 
DETAILPEN, 57 
Determining Chip Versions, 537 
Device 

asynchronous lORequests, 449 

closing, 450 

commands, 448 

device base address pointer, 452 

device names, 447 

device specific command prefixes, 448 

devices with functions, 452 

error checking, 450 

error indications, 450 

gracefully exiting, 451 

opening, 447 

passing lORequests, 447 

problems, 917 

romtag, 444 

sharing library bases, 467 

standard Exec commands, 448 

synchronous lORequests, 449 

task structure fields for, 466 
Device (Exec), 435 
DHeight 

in ViewPort, 542, 550, 

in ViewPort display memory, 549 
DiagArea structure, 761 
Dimensionlnfo structure, 543 
DISABLE, 519, 530 

mutual-exclusion mechanism, 519 
DISABLE macro, 470 
Disabled, 470, 480, 520, 530 
Disabling 

interrupts, 470, 520, 530, 

maximum disable period, 471 
Disk 

inserted message, 262, 

removed message, 262 
DiskFontHeader structure, 699 
diskfont.library - see Text 
DisownBlitterQ, 599, 599, 612 
Dispatcher, 305 
Display Clip, 40, 46, 49, 59, 61 , 62, 86 

default, 63 
Display Colors, 536 
Display Database, 20 

display limitations, 47, 

display mode, 47 
Display Modes, 47, 536, 545 

screens, 37 
Display Requirements 

Table, 536 
Display width 

affect of overscan on, 535, 

effect of resolution on, 547 
DisplayAlert(),221,222 
DisplayBeepO, 75, 204 
DisplayClip, 541 
DisplaylD, 59 
Displaylnfo 

handle, 564 
Displaylnfo structure, 553, 567 
DisplaylnfoHandle, 566, 567 
DisposeCxMsgO, 746 
DisposeObject(), 295, 330 
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DisposeRegion(), 720 
DivertCxMsgO, 746 
DMA 



displaying the View, 555, 

playfield, 543 
DoCollisionQ, 646, 668 
DolO(), 447, 449 
DoMethod(), 302, 330, 890 
DoMethodAQ, 302, 330, 890 
DOS 

compatibility, 925, 

problems, 917 
DOS Commands 

executing, 20 
DosEnvc structure, 760 
DoSuperMethodO, 310, 330, 890 
DoSuperMethodA(), 308, 310, 330, 890 
Dotted lines, 585 
Double Click 

definition, 265, 

right mouse button, 202, 21 
Double Menu Requester, 210 
Double-buffering 

allocations for, 579, 

Copper in, 579, 

Copper lists, 629 
DoubleClick(), 269, 282 
Drag 

definition, 265, 

enable gadget, 109 
Drag Bar 

cancel window drag, 77, 

screens, 39, 

window, 77 
Drag Select, 267 

menus, 169 
Draw(), 588, 61 1 

in line drawing, 588, 

multiple line drawing, 589 
DrawBevelBox(), 403, 413 
DrawBevelBoxA(), 403, 413 
DrawBorderf), 224, 224, 235, 237, 244 
DrawCircle(), 588, 611 
DrawEllipsef), 588, 611 
DrawerData structure, 352 
DrawGListO, 288, 642, 668 

preparing the GELS list, 628 
DrawlmageO, 224, 224, 225, 226, 227, 244 
Drawlnfo structure, 47, 55, 56, 58, 59, 106, 225, 238 

driFont, 58 

driPens, 57, 107 

driVersion, 55 
Drawing 

and Intuition text, 240 

changing part of drawing area, 594 

clearing memory, 592 

colors, 584 

in complement mode, 585 

lines, 588 

memory for, 582 

modes, 585 

moving source to destination, 595 

pens, 584 

pixels, 587 

shapes, 590 

turning off outline, 590 

with Image structure, 225, 227 
Drawing pens 

color, 584, 

current position, 587 
DrawMode 

and Intuition text, 239 

border, 234 

in Border structure, 237 

in flood fill, 591 

in stencil drawing, 594 

Intuition text, 242 

with BltTemplate(), 596 
DRI_VERSION, 55 
DSKBLK Interrupts, 519 
DSKSYNC Interrupts, 519 
Dual playfield 

bitplanes, 578 

color map, 554 

colors, 545 

priority, 578 



with screens, 70 
DUALPF, 70, 545 
DWidth 

in ViewPort, 542, 550, 

in ViewPort display memory, 549 
DxOffset 

effect on display window, 550, 

in ViewPort display memory, 549 
DyOffset 

effect on display window, 550, 

in ViewPort display memory, 549 
EasyRequestQ, 1 1 2, 1 88, 201 , 21 1 , 21 5, 21 6, 216-21 7, 218, 
219ries/Lib_7/7-5}, 222 
EasyRequestArgsQ, 112, 215-216, 222 
EasyStruct structure, 216 

es_Flags, 21 6 

es_GadgetFormat, 216, 217 

es_StructSize, 216 

es_TextFormat, 216, 217 

es_Title, 216 
ECS, 11 

and genlock, 607, 

determining chip versions, 537 
Emergency 

message, 220 
ENABLE, 530 
ENABLE macro, 470 
Enable(), 470, 480, 520, 530 
End gadget 

requester, 206 
EndNotifyO, 336, 344 

EndRefresh(), 95, 97, 97, 110, 115, 128,244,261,721 
EndRequestO, 112, 203, 206, 222 
EndUpdateO, 128, 711,721 
Enhanced Chip Set, 11 
Enqueue)), 492, 498 
EnqueueCxObj(), 737 
EntryHandler(), 797, 798, 810 
EO_BADFORMAT, 1 60 
EO_BIGCHANGE, 160 
EO_CLEAR, 160 
EO_DELBACKWARD, 160 
EO_DELFORWARD, 160 
EO_ENTER, 160 
EOJNSERTCHAR, 160 
EOJvlOVECURSOR, 160 
EO_NOOP, 160 
EO_REPLACECHAR, 160 
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EO_RESET, 160 
EO_SPECIAL, 160 
EOJJNDO, 160 
Eraselmage(), 225 
EraseRectf), 225 
Error 

display, 204 

incorrect custom chips, 45 
monitor not available, 45 
no Chip memory, 45 
no memory, 45 
open screen, 45 
screen name collision, 45 
unknown mode, 45 
Errors, 915 

Escape Sequences, 90 
ANSI, 248, 
console device, 248 
Event Loop 

IDCMP, 250, 251 
Events, 481 
Examples 

Animation 

complete bobs example, 642 
ASL 

custom hook function, 426 
file requester with multiple selection, 41 £ 
file requester with pattern matching, 41 9 
font requester, 424 
simple file requester, 417 
Boopsi 

custom gadget class, 323 



custom model subclass, 312 

Talk2boopsi.c, 299 
Commodities 

custom CxObject for swapping mouse buttons, 
744 

hotkey pop-up shell commodity, 750 

input description strings, 737 

monitoring user inactivity, 747 

opening a broker commodity, 731 

simple hot key commodity, 738 

compiler flags used, 12 
Exec 

building and reading a list, 495 

calling a library function, 437 

Ctrl-C Processing, 433 

library source code, 909 

open an Exec Library, 438 

opening a library (in assembler), 5 

opening a library (in C), 4 

semaphores, 514 

signals.c, 484 

simpletask.c, 467 

task creation, 467 

task list, 471 

task trap, 475 

using an Exec device, 453 
Expansion 

DiagArea in RAM, 762 

list AUTOCONFIG boards, 757 

sample autoboot code, 763 

sample AUTOCONFIG ROM, 767 
Gadgets 

creating a simple gadget, 1 20 

scroller support functions, 144 

slider support functions, 145 

string gadget with edit hooks, 162 

updating a string gadget, 151 
GadTools 

complete GadTools example, 406 

gadget message filtering, 403 

NewMenu structure, 369 

slider gadget setup, 393 

using CreateContext(), 400 

using gadgets, 383 

using the menu system, 372 

using Visuallnfo functions, 399 
graphics, 571 

animtools.c, 661 

RGBBoxes.c, 556 

UserCopperExample.c, 603 
IFFParse 

ClipFTXT.c, 803, 

Sift.c, 807 
Intuition 

allocremember.c, 285 

blocking input with a requester, 207 

CloseWindowSafelyO for shared IDCMPs, 255 

compleximage.c, 231 

custompointer.c, 275 

displayalert.c, 221 

easyintuition33.c, 34 

easyintuition37.c, 32 

easyrequest.c, 21 7 

IDCMP event loop, 251 

input event loop, 31 

intuitext.c, 241 

rawkey.c, 277 

read mouse, 269 

remembertest.c, 286 

shadowborder.c, 235 

simpleimage.c, 228 
Keymap 

AskKeyMap(), 813 

German keymap excerpt, 824 

mapping RAWKEY events to character 
sequences, 814 

mapping text to keypresses, 816 

SetKeyMapO, 813 
Menus 

menu layout, 1 92, 

simple menu, 172 
Messages 

skeleton of waiting for a signal, 434 



Preferences 



Screens 



Text 



Windows 



prefs file change notification, 336 
read and parse IFF Prefs, 341 

cloning a public screen, 59 
double buffered screen, 67 
dual playfield screen, 70 
finding the Workbench screen, 51 
opening a new look screen, 42 
opening screens compatibly, 44 
using a public screen, 56 

list available fonts, 690 
measuring and fitting text, 678 
render a text file to a window, 684 
sample font source, 699 
skeleton for opening a font, 671 
skeleton for selecting aspect ratio, 683 
skeleton for soft styling a font, 675 
skeleton using AvailFonts(), 689 

calculating window border size, 89 
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opening a window with tags, 80 

superbitmap window, 99 

using public screens, 83 

window sized to the visible display, 86 

Workbench 

Applcon, 360 
AppMenultem, 361 
AppWindow, 363 
icon creation and parsing, 355 
parse Workbench and CLI args, 349 
Exception signal, 473 
Exceptions, 473 

680x0, 473 

Exec, 473 

SetExceptO, 473 

synchronous, 474 

tc_ExceptCode, 473 

tc_ExceptData, 473 
Exec 

CloseLibrary(), 436 

Device, 435 

examples 

building and reading a list, 495 
calling a library function, 437 
Ctrl-C Processing, 433 
library source code, 909 
Open an Exec Library, 438 
opening a library (in assembler), 5 
opening a library (in C), 4 
semaphores, 514 
task signalling, 484 
tasklist.c, 471 
trap_c.c, 475 

introduction to, 9 

Kickstart version, 435 

Library, 435 

version, 435 

Library Vector Offset - see LVO 

LINKLIB macro, 438 

LVO, 436, 437 

MEMF_CHIP, 14 

MEMF_FAST, 14 

Messages 

interprocess communication, 433 

multitasking, 429 

OpenLibrary(), 3, 4, 435 

process, 430 

quantum, 430 

SetSignalQ, 433 

Signals, 432 

struct Library, 436, 441 

struct Task, 465 

task, 429, 430 

WaitQ, 30, 31,432 
ExecBase Structure, 518, 520 
exec/errors. h, 450 
ExitHandler(), 797, 810 
Expansion, 924 



AddBootNode(), 759, 776 
AddDosNode(), 759, 776 
autoboot 

BOOT, 768, 
DIAG, 761, 
ROMTAG INIT, 768 
AUTOCONFIG, 755 

hardware manufacturer number, 756 
ConfigDev flags, 756 
device drivers, 758 
DiagArea flags, 761 

disk based expansion board drivers, 758 
examples 

DiagArea in RAM, 762 
list AUTOCONFIG boards, 757 
sample autoboot code, 763 
sample AUTOCONFIG ROM, 767 
expansion board drivers 
Autoboot, 760, 
ROM based, 760 
FileSysRes, 775 
FileSysResource, 769 
FindConfigDev(), 756, 757, 776 
GetCurrentBinding(), 759, 776 
Hardware Manufacturer Number, 756 
InitResidentO, 759 
MakeDosNodeO, 759, 776 
ObtainConfigBinding(), 759 
ReleaseConfigBinding(), 759 
RigidDiskBlock, 769, 

see also "SCSI Device" in RKM:Devices 
BadBlockBlock, 772 
Environment, 773 
FileSysHeaderBlock, 774 
LoadSegBlock, 775 
PartitionBlock, 773 
RigidDiskBlock specification, 770 
SetCurrentBinding(), 759, 776 
struct ConfigDev, 756 
struct CurrentBinding, 759 
struct DiagArea, 761 
struct DosEnvc, 760 
struct ExpansionRom, 757 
ExpansionRom structure, 757 
Expunge vector, 437 
Extended 

new screen structure, 46 
EXTER, 519, 525, 526 
EXTER Interrupts, 519, 525 
ExternFontO, 682 
ExtNewScreen structure, 43, 45 
ExtNewWindow structure, 80, 106 
Extra-Half-Brite 

Clearing Plane 6, 583, 
Setting Plane 6, 583 
Extra-Half-Brite mode, 580 
EXTRAJHALFBRITE, 545-546 
Fast floating-point library, 833 
Fast Memory, 11, 431, 456 
FastRand(), 887 
FCHJD, 698 
fclose(), 887 
fgetc(), 887 
FgPen 

in complement mode, 585 
in flood fill, 590, 591 
in JAM1 mode, 584 
in line drawing, 588 
in RastPort, 584 
in rectangle fill, 592 
with BltTemplate(), 596 
File 

requester, 20 
FileRequester structure, 416 
FileSysResource, 769 
FILF_DOMSGFUNC, 425 
FILF_DOWILDFUNC, 425 
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FILFJvlULTISELECT, 419 
FILFJMEWIDCMP, 419 
FILF_PATGAD,419 



FILF_SAVE, 419 
FILLPEN, 58 
fillrectclass, 297 
FILLTEXTPEN, 58 
Filter 

IDCMP messages, 250 
FinalPC, 463 
FindCollection(), 785, 810 
FindConfigDev(), 756, 757, 776 
FindDisplaylnfoO, 567, 567,611 
FindLocalltem(), 791,810 
FindName(), 493, 498, 520 
FindPortO, 502, 520 
FindPropQ, 344, 783,810 
FindPropContextO, 798, 810 
FindSemaphore(), 514, 515 
FindTask(), 49, 480, 520 
FindToolType(), 354 
First-In-First-Out (FIFO), 492, 499 
Flags 

menu item, 191 

new window, 111 

window, 109 

with BNDRYOFF() macro, 590 
Flicker 

menu items, 181 
Flood(), 590, 611 
Follow mouse, 273 
FONF_BACKCOI_OR, 423 
FONFJ30MSGFUNC, 425 
FONF_DOWILDFUNC, 425 
FONFJ3RAWMODE, 423 
FONF_FIXEDWIDTH, 423 
FONF_FRONTCOLOR, 423 
FONF_STYLES, 423 
Font, 930 

in easy requester, 215 

in screen, 59 

Intuition text, 243 

life, 58 

menu layout, 179 

outline, 19 

preferred, 48 

preferred monospace, 48 

requester, 20 

SA_Font, 58 

SA_SysFont, 58 

scaling, 19 

screen, 47, 58 

system font in screen, 48 

window, 85 

window title, 107 
FontContents structure, 698 
FontContentsHeader structure, 698 
FontExtentO, 155,676 
FontPrefs structure, 338 
FontRequester structure, 422 
Forbidf), 1 1 0, 366, 470, 480, 520 
Foreground pen, 584 
Format String 

easy requester, 21 7 
fpa(), 888 

FPF_DESIGNED, 671 
FPF_DISKFONT, 671 
FPF_PROPORTIONAL, 671 
FPF_REVPATH, 671 
FPF_ROMFONT, 671 
FPF_TALLDOT, 671 
FPFJ/VIDEDOT, 671 
fprintf(), 887 
fputcQ, 887 
fputs(), 887 
frameiclass, 297 
frbuttonclass, 298 
Free memory, 463 
FreeAslRequest(), 416 
FreeClass(), 330 
FreeColorMapO, 560, 610 
FreeCprList(), 560, 610 
FreeDiskObject(), 353 
FreeEntry(), 459, 462 
FreeGadgets(), 382, 413 
FreeGBuffersQ, 668 



FREEHORIZ, 147 

FreelEventsO, 749, 889 

FreelFF(), 344, 810 

Freel_ocalltem(), 799, 810 

FreeMem(), 284, 431, 455, 457 

FreeMenusf), 377, 413 

FreeRasterQ, 560, 610 

FreeRemember(), 283, 284, 284-285, 289 

FreeScreenDrawlnfoQ, 56, 76, 244 

FreeSignalO, 476, 482, 485 

FreeSpriteO, 620, 668 

FreeSysRequestf), 219, 222 

FreeTrap(), 476, 480 

FreeVecO, 431 

FREEVERT, 147 

FreeVisuallnfo(), 413 

FreeVPortCopListsf), 560, 610 

FSF_BOLD, 671 

FSF_EXTENDED, 671 

FSFJTALIC, 671 

FSFJJNDERLINED, 671 

FTXT, 799 

FULLMENU(), 178 

FULLMENUNUMQ, 200 

GACT_ALTKEYMAP, 137 

GACT_BOOLEXTEND, 137 

GACT_BOOLEXTENDED, 138 

GACT_BOTTOMBORDER, 126, 137 

GACT_ENDGADGET, 136, 206 

GACT_FOLLOWMOUSE, 131, 136, 258, 273 

GACTJMMEDIATE, 123, 124, 131, 136, 259 

GACT_LEFTBORDER, 126, 137 

GACTJ_ONGINT, 133, 137, 150, 160 

GACT_RELVERIFY, 123, 124, 131, 136,259 

GACT_RIGHTBORDER, 126, 136 

GACT_STRINGCENTER, 137, 154 

GACT_STRINGEXTEND, 137 

GACT_STRINGLEFT, 137, 154, 155 

GACT_STRINGRIGHT, 137, 154 

GACT_TOGGLESELECT, 136, 138 

GACT_TOPBORDER, 126, 137 

Gadget, 318 - see Also BOOPSI and GadTools 

actions with SGH_KEY, 161 

ActivateGadgetO, 150, 166, 321 

activating a string gadget, 150 

Activation flags, 123-124, 126, 131, 136-137, 154 

active gadget, 323 

AddGadget(), 166 

AddGListQ, 122,129,166 
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adding a gadget, 121 

adjusting borders, 126 

alternate border, 118, 127, 128 

alternate image, 118, 127, 128 

and requester, 204 

Auto-Knob for proportional gadgets, 143 

BeginRefresh(), 128 

BeginUpdate(), 128 

boolean gadgets, 129 

boolinfo flags, 139 

border gadgets, 126 

Border Structure, 128 

box gadget highlighting, 127, 128 

button gadget, 118 

Caveats 

do not share knob imagery, 143 
do not use image lists for knobs, 143 
GimmeZeroZero window border, 136 
imagery and the selection box, 124 
mouse tracking with boolean gadgets, 136 

close gadget, 1 1 9 

complement gadget highlighting, 127, 127 

custom gadgets, 1 66 

defined, 28 

depth gadget, 119 

disabling, 118, 130 

down, 268 

down message, 259 

drag gadget, 1 1 9 

enabling, 118, 130 

EndRefreshQ, 128 



EndllpdateO, 128 

Examples 

creating a simple gadget, 120 
scroller support functions, 144 
slider support functions, 145 
string gadget with edit hooks, 162 
updating a string gadget, 151 

FontExtentO, 155 

gadget flags, 122, 124, 127, 128, 128, 134, 154, 157 

gadget imagery, 122 

Gadget Structure, 119 

GadgetID, 134 

gadgets without imagery, 123 

GFLG_DISABLED, 321 

ghosted 

see Gadgets disabling 

GMR_MEACTIVE, 321 

GMR_NEXTACTIVE, 321 

GMR_NOREUSE, 321 

GMR_PREVACTIVE, 321 

GMR_REUSE, 321 

GMJ30INACTIVE, 322 

Help key in string gadgets, 158 

highlighting, 118 

highlighting gadgets, 127 

highlighting mutual exclude, 139 

hit-select boolean gadget, 138 

IDCMP Messages, 123-124, 128, 131 

Image Structure, 128 

imageless gadgets for mouse tracking, 123 

implemention of, 318 

in borders, 932 

in new window, 107 

in requester, 204, 206 

in window border, 93 

integer gadget, 150 

Intuition Message classes, 119 

Knob on proportional gadgets, 142 

left mouse button, 118 

Methods, 318 

modifying gadgets, 122 

Modify Prop(), 166 

mutually exclusive, 140 

NewModifyPropf), 147, 148, 166 

ObtainGIRPort(), 323 

OffGadget(), 130, 166 

OnGadget(), 130,166 

position, 124 

Proplnfo flags, 140, 147 

proportional gadget, 118, 140 

proportional gadget container, 142 

proportional gadget increment, 144 

proportional gadget knob, 142 

RefreshGadgets(), 166 

RefreshGListO, 128, 129, 130, 166 

refreshing gadgets, 128 

relative position, 124 

relative size, 124 

ReleaseGIRPortO, 323 

RemoveGadgetQ, 166 

RemoveGListO, 122, 166, 322 

removing a gadget, 121 

screen gadgets, 119 

Scroller, 141, 141 

select box size, 125 

select button, 118 

SetEditHookQ, 166 

SGWork editing actions, 160 

SGWork editing operations, 160 

size gadget, 119, 124 

Slider, 141, 142 

Speciallnfo, 134 

string gadget, 118, 148 

string gadget editing, 158 

string gadget modes, 157 

string gadget with an alternate keymap, 1 56 

struct Boollnfo, 139 

struct Border, 123 

struct Gadget, 132 

struct IntuiMessage, 119 

struct IntuiText, 123 

struct Proplnfo, 143, 144, 147 

struct SGWork, 159 



struct StringExtend, 157 

struct Stringlnfo, 154, 155 

system gadgets, 77, 91 , 1 1 9 

text gadget, 118 

text justification, 154 

toggle-select boolean gadget, 138 

types of gadgets, 133, 138 

up, 268 

up message, 259 

UserData, 134 

using relative positioning, 125 

window gadgets, 119 

zoom gadget, 119 
Gadget structure, 132, 224, 352 

1.3 compatible usage, 19 

activation, 93, 206 

GadgetType, 206, 212 
Gadget Toolkit - see GadTools 

Index 947 

gadgetclass, 292, 297 
Gadgetlnfo structure, 318 
GadTools, 192, 367 

BUTTON_KIND 

GA_Disabled, 386, 387 

GAJTabCycle, 387 

GTIN_MaxChars, 387 

GTIN_Number, 387 

GTST_MaxChars, 387 

GTST_String, 386 

STRINGA_ExitHelp, 387 

STRINGAJustification, 387 

STRINGA_ReplaceMode, 387 
caveats 

GadTools enforces Intuition limits, 375 

GT_SetGadgetAttrs() & GT_BeginRefresh(), 386 

PLACETEXT with GENERIC_KIND gadgets, 398 

post-processing, 368 

preserve bits set by CreatsGadgetf), 398 

refreshing the display, 382 

restrictions on gadgets, 41 1 

side effects, 412 
CHECKBOX_KIND 

GA_Disabled, 389 

GTCB_Checked, 389 
controlling gadgets from the keyboard, 404 
CreateContext(), 399 
CreateGadget(), 380 
CreateMenusQ, 374 
CreateMenusA(), 374 
creating gadgets, 380 
CYCLE_KIND 

GA_Disabled, 390 

GTCY_Active, 390 

GTCYJ_abels, 390 
DrawBevelBoxQ, 403 
DrawBevelBoxA(), 403 
examples 

complete GadTools example, 406 

gadget message filtering, 403 

NewMenu structure, 369 

slider gadget setup, 393 

using CreateContext(), 400 

using gadgets, 383 

using the menu system, 372 

using Visuallnfo functions, 399 
features of, 368 
FreeGadgetsO, 382 
FreeMenus(), 377 
function descriptions, 413 
gadget types, 378, 386 

button, 378, 386 

checkboxes, 378, 389 

cycle, 378, 390 

generic gadget, 398 

integer, 378, 386 

listviews, 378, 394 

mutually exclusive, 378, 389 

numeric-display, 378, 397 

palette, 378, 396 

scrollers, 378, 393 

sliders, 378, 391 



string, 378, 386 

text-display, 378, 397 
gadgets, 378 
GetVisuallnfoO, 398 
GetVisuallnfoA(), 398 
GTMENUITEMJJSERDATA(), 372 
GTMENUJJSERDATA(), 372 
GTMNJ=rontPen(), 374 
GTMNJTextAttr, 375 
GTBeginRefreshQ, 402 
GTJEndRefresh(), 402 
GT_FilterlMsg(), 402 
GT_GetlMsg(), 381 
GT_PostFilterlMsg(), 402 
GT_RefreshWindow(), 401 
GTJReplylMsgO, 381 
GT_SetGadgetAttrs(), 385 
GT_SetGadgetAttrsA(), 385 
handling gadget messages, 381 
IDCMP flags, 382 

implementing gadget keyboard equivalents, 404 
language-sensitive menus, 378 
LayoutMenultems(), 376 
LayoutMenultemsA(), 376 
LayoutMenus(), 375 
LayoutMenusA(), 375 
LISTVIEW_KIND 

GTLVJ_abels, 394 

GTLV_ReadOnly, 395 

GTLVJScrollWidth, 395 

GTLVJSelected, 395 

GTLVJShowSelected, 395 

GTLVJop, 395 

LAYOUTA_Spacing, 395 
menu layout, 180 
menus, 368 

menus and intuimessages, 377 
minimal IDCMP_REFRESHWINDOW processing, 402 
modifying gadgets 

struct, 385 
MX_KIND 

GTMX_Active, 389 

GTMXJ_abels, 389 

GTMXJSpacing, 390 
NUMBER_KIND 

GTNMJ3order, 397 

GTNM_Number, 397 
PALETTE J<IND 

GA_Disabled, 396 

GTPA_Color, 396 

GTPA_ColorOffset, 396 

GTPAJ3epth, 396 

GTPAJndicatorHeight, 396 

GTPAJndicatorWidth, 396 
programming gadgets, 378 
restrictions on menus, 377 
reusing a NewGadget structure, 401 
SCROLLER_KIND 

GA_Disabled, 394 

GAJmmediate, 394 

GA_RelVerify, 394 

GTSC_Arrows, 394 

GTSCJTop, 393 

GTSCJTotal, 393 

GTSCJ/isible, 393 

PGAFreedom, 394 
SLIDER_KIND 

GA_Disabled, 392 

GAJmmediate, 392 

GA_RelVerify, 392 

GTSLDispFunc, 392 

GTSLJ_evel, 391 

GTSL Level Format, 391 
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GTSLJ_evelPlace, 391 

GTSL_Max, 391 

GTSLMaxLevelLen, 391 

GTSL_Min, 391 

PGAFreedom, 392 
processing IntuiMessages, 392 
struct NewGadget, 379 



struct NewMenu, 370 

TEXT_KIND 

GTTX_Border, 397 
GTTX_CopyText, 397 
GTTX_Text, 397 
Gameport device, 925 

GA_Disabled, 386, 387, 389, 390, 392, 394, 396 
GAJmmediate, 392, 394 
GA_RelVerify, 301, 392, 394 
GAJTabCycle, 387 
GA Underscore, 404 
GELGONE Flag 

in VSprite structure, 624 
GELS 

introduction, 613, 

types, 614 
Gelslnfo, 583 
Gelslnfo structure, 632 
Genlock, 607, 607 

control, 20 
GetAttr(), 296, 301,330 
GetCC(), 478 
getchar(), 887 

GetColorMapO, 47, 553, 560, 564, 610 
GetCurrentBinding(), 759, 776 
GetDefaultPubScreen(), 50, 76 
GetDefDiskObject(), 353 
GetDefPrefs(), 332, 344 
GetDiskObjectQ, 353 
GetDiskObjectNew(), 353 
GetDisplaylnfoData(), 543, 567, 61 1 
GetGBuffersO, 668 
GetMsgQ, 434, 505, 520 
GetPrefsQ, 262, 332, 344 
GetRexxVar(), 888 
GetRGB4(), 554 
GetScreenData(), 51, 59, 75, 76 
GetScreenDrawlnfo(), 56, 59, 76, 244 
GetSpriteO, 619, 668 
GetVisuallnfoO, 398, 413 
GetVisuallnfoAf), 398, 413 
GetVPModelDQ, 59, 566, 611 
GFLGJ3ISABLED, 130, 135, 321 
GFLG_GADGHBOX, 127, 128, 129, 134 
GFLG_GADGHCOMP, 127, 127, 134 
GFLG_GADGHIMAGE, 127, 128, 129, 134 
GFLG_GADGHNONE, 127, 134 
GFLG_GADGIMAGE, 122, 123, 123, 128, 134 
GFLG_RELBOTTOM, 125, 128, 135 
GFLG_RELHEIGHT, 125, 128, 135 
GFLG_RELRIGHT, 124-125, 128, 135 
GFLGJRELVERIFY - Boopsi gadgets, 301 
GFLG_RELWIDTH, 125, 128, 135 
GFLGJ3ELECTED, 135 
GFLG_STRINGEXTEND, 135, 155, 157 
GFLGJTABCYCLE, 135, 154 
GfxAssociate(), 551,611 
GfxBase Structure, 243 

DefaultFont, 58, 85, 241 , 243 
GfxFree(),551,611 
GfxLookUpf), 551 
GfxNewQ, 551,611 
Ghosted 

menus, 185 
GimmeZeroZero, 133 

attribute, 110 

border rast port, 105 

clipping alternative, 93 

description, 93 

gadget in border, 89 

mouse position, 105, 273 

offset alternative, 89 

opening, 93 

requester limit, 204 

requester positioning, 93 

use of resources, 93 

window type, 92, 93 

with borderless, 92 

with superbitmap, 96 
GLFG_RELVERIFY 

Boopsi Gagdets, 301 
GMR_GADGETHIT, 320 
GMRJvlEACTIVE, 321 



GMR_NEXTACTIVE, 321 
GMR_NOREUSE, 321 
GMR_PREVACTIVE, 321 
GMR_REUSE, 321 
GMJ30ACTIVE, 318, 320 
GMJ30INACTIVE, 318, 322 
GMJHANDLEINPUT, 318, 321 
GMJHITTEST, 318, 320 
GM_RENDER, 318, 319 
gpGolnactive structure, 322 
gpHitTest structure, 320 
gplnput structure, 320 
gpRender structure, 319 
Graphics 

display modes, 536 

examples 

Animation tools, 661 
simple ViewPort creation, 556 
User copper list, 603 
WBCIone.c, 571 

high level interface, 223 

images, 919 

in windows, 85 

layers locking, 707, 726 

screen data organization, 39 

struct AnimComp, 652 

struct AnimOb, 652 

struct bltnode, 600 

struct RastPort, 581 

text - see Text 

using from Intuition, 223 

with layers, 704 
graphics. library - see also Text 
GREDRAW_REDRAW, 319 
GREDRAW_TOGGLE, 319 
GREDRAWJJPDATE, 319 
groupgclass, 297 
GTCB_Checked, 389 
GTCY_Active, 390 
GTCY_Labels, 390 
GTINJvlaxChars, 387 
GTINJMumber, 387 
GTLV_Labels, 394 
GTLV_ReadOnly, 395 
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GTLV_ScrollWidth, 395 
GTLV_Selected, 395 
GTLV_ShowSelected, 395 
GTLVTop, 395 
GTMENUJNVALID, 375 
GTMENUITEM_USERDATA(), 372 
GTMENU_NOMEM, 375 
GTMENU_TRIMMED, 375 
GTMENUJJSERDATA(), 372 
GTMN_FrontPen(), 374 
GTMN_FullMenu, 374 
GTMNJvlenu, 376 
GTMNSecondaryError, 375 
GTMN_TextAttr, 375, 376 
GTMX_Active, 389 
GTMXJ_abels, 389 
GTMX_Spacing, 390 
GTNM_Border, 397 
GTNM_Number, 397 
GTPA_Color, 396 
GTPA_ColorOffset, 396 
GTPA_Depth, 396 
GTPAJndicatorHeight, 396 
GTPAJndicatorWidth, 396 
GTSC_Arrows, 394 
GTSCJTop, 393 
GTSCJTotal, 393 
GTSC_Visible, 393 
GTSLDispFunc, 392 
GTSL_l_evel, 391 
GTSLLevel Format, 391 
GTSL_l_evelPlace, 391 
GTSL_Max, 391 
GTSLMaxLevelLen, 391 
GTSL_Min, 391 
GTST_MaxChars, 387 



GTST_String, 386 
GTTX_Border, 397 
GTTX_CopyText, 397 
GTTX_Text, 397 
GTYP_BOOLGADGET, 133, 138 
GTYP_CUSTOMGADGET, 133 
GTYP_GZZGADGET, 89, 93, 133, 136 
GTYP_PROPGADGET, 133 
GTYP_REQGADGET, 133, 206, 212 
GTYP_STRGADGET, 133, 154 
GT_BeginRefresh(), 402, 413 
GT_EndRefresh(), 402, 413 
GT_FilterlMsg(), 402, 413 
GT_GetlMsg(),381,413 
GT_PostFilterlMsg(), 402, 413 
GT_RefreshWindow(), 401, 413 
GT_ReplylMsg(),381,413 
GT_SetGadgetAttrs(), 385, 413 
GT_SetGadgetAttrsA(), 385, 413 
GUI - see Boopsi 
HAM, 545-546, 580-581 
Hardware 

differences, 926 
Hardware Interrupts, 517 
Hardware Sprites 

reserving, 632 
Height 

by inner dimension, 108 

in ViewPort, 542 
Height variable 

in VSprite structure, 625 
Help 

menu, 111, 260 
HIGHBOX, 192 
HIGHCOMP, 191 
HIGHFLAGS, 191 
HIGHIMAGE, 190, 192,225 
HIGHITEM, 192 
Highlighting 

menu item, 191, 

menus, 169, 169 
HIGHLIGHTTEXTPEN, 58 
HIGHNONE, 192 
HIRES, 545 

Hold-and-modify mode, 580 
Hook structure, 312 
HookEntry.asm, 794 
Hooks, 875 

example, 877 

function, 875 

function reference, 883 

structure, 875 

usage, 876 
Hot Spot 

mouse, 266 
HotKey(), 889 
ICA_MAP 

Boopsi gadgets, 299, 

icclass, 302 
ICA_TARGET, 309 

Boopsi gadgets, 298, 302, 

icclass, 302 
icclass, 292, 297, 302 
Icon 

creation, 350, 

parsing, 350 
Icon library, 350 
IControlPrefs structure, 338 
ICSPECIAL_CODE 

Boopsi gadgets, 302 
IDCMP, 31,247 

application allocated, 249 

Boopsi, 301 

creation, 249 

definition, 90 

discard messages, 113 

Flags, 257 

freeing, 249 

in easy requesters, 215 

input events, 249 

message structure, 250 

queue limits, 113 

requester, 210 



IDCMP_ 
IDCMP_ 
IDCMP_ 
IDCMP_ 
IDCMP_ 
IDCMP_ 
IDCMP_ 
IDCMP_ 

IDCMP_ 

IDCMP_ 
IDCMP_ 
IDCMP_ 
IDCMP_ 
IDCMP_ 
IDCMP_ 
IDCMP_ 
263-264 



shared, 253-254 

WAJDCMPtag, 107 
ACTIVEWINDOW, 91 , 1 76, 261 
CHANGEWINDOW, 263 
CLOSEWINDOW, 248, 259 
DELTAMOVE, 256, 259, 268-269 
DISKINSERTED, 262 
DISKREMOVED, 262 
GADGETDOWN, 1 1 9, 1 23, 1 24, 259, 268 
GADGETUP, 119, 123, 124, 131,259,268 

Boopsi gadgets, 301 
JDCMPUPDATE, 263 

Boopsi gadgets, 302 
INACTIVEWINDOW, 91, 261 
INTUITICKS, 74, 258, 262-263 
LONELYMESSAGE, 263 
MENUBUTTONS, 186 
MENUHELP, 111, 178, 179,258,260 

MENUPICK, 176, 177, 177, 179, 185, 186, 187, 187, 259, 268 
MENUVERIFY, 49, 186, 186, 186, 187, 188, 216, 259-260, 
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IDCMPJvlOUSEBUTTONS, 110, 131, 175, 187,258,268,269 

IDCMPJvlOUSEMOVE, 93, 109, 124, 131, 256, 258, 259, 268, 269, 273 

IDCMP_NEWPREFS, 262, 332 

IDCMP_NEWSIZE, 112,260 

IDCMP_RAWKEY, 256, 261-262, 277, 277 

IDCMP_REFRESHWINDOW, 97, 110, 128, 261 

IDCMP_REQCLEAR, 105, 210, 210, 260 

IDCMP_REQSET, 105, 210, 210, 260 

IDCMP_REQVERIFY, 21 1 , 260, 263-264 

IDCMP_SIZEVERIFY, 91 , 250, 261 , 263-264 

IDCMPJJPDATE, 277 

IDCMP_VANILLAKEY, 256, 261, 277 

IDCMPJ/VBENCHMESSAGE, 263 

IDNestCnt Counter, 530 

IEQUALIFIER_CAPSLOCK, 282 

IEQUALIFIER_CONTROL, 282 

IEQUALIFIERJ_ALT, 282 

IEQUALIFIERJ_COMMAND, 282 

IEQUALIFIERJ_EFTBUTTON, 282 

IEQUALIFIERJ_SHIFT, 282 

IEQUALIFIERJvIIDBUTTON, 282 

IEQUALIFIER_NUMERICPAD, 282 

IEQUALIFIER_RALT, 282 

IEQUALIFIER_RBUTTON, 282 

IEQUALIFIER_RCOMMAND, 282 

IEQUALIFIER_REPEAT, 277, 282 

IEQUALIFIER_RSHIFT, 282 

IFEMPTY, 498 

IFF, 777 

Chunk, 778 

example file, 780 

FORM, 778-779 

size, 780 

FORM types, 799 

FTXT, 803 

ILBM, 800, 801,802 

introduction, 778 

Preferences, 338 
IFFHandle structure, 780 
IFFParse, 777 

context stack, 789 

custom chunk handler, 797, 798 

custom stream handler, 793-795, 795 

error handling, 792 

examples 

examining IFF files, 807 

parsing FTXT for the clipboard, 803 

reading files, 784 

streams, 781 

struct ContextNode, 789 

struct IFFHandle, 780 

writing files, 787 
IFNOTEMPTY, 498 
ILBM, 799 

Illegal instruction, 474 
Image 

menu item, 169, 190, 

position, 224 
Image structure, 180, 190, 191, 192, 223, 224, 224-225, 225, 353 



bit-plane organization, 227 

calculation of data size, 226 

color computation, 228 

Depth, 226, 231 

Height, 226, 231 

ImageData, 226, 227, 231 

LeftEdge, 226, 240 

Nextlmage, 226 

PlaneOnOff, 226, 230-231 

PlanePick, 226, 230 

TopEdge, 226, 240 

Width, 226, 231 
imageclass, 292, 297 
ImageData 

changing VSprites, 627 
ImageData pointer 

in VSprite structure, 625 
Imagery 

in requester, 204, 

in requester gadgets, 206 
Images - see also Boopsi 
IMJTEM, 370 
IM_SUB, 370 
inheritance, 293, 306, 31 1 
InitAreaO, 582, 611 
InitBitMapO, 98, 552, 610 
InitGelsO, 668 
InitGMasksO, 668 
lnitlFF(), 781,810 
InitlFFasClipQ, 781,810 
InitlFFasDOSO, 344, 781, 810 
InitMasksO, 648, 668 
InitRastPortO, 582, 611 
lnitRequester(), 203, 21 1 , 222 
InitResidentQ, 759 
InitSemaphoreO, 511, 515 
lnitStruct(), 462 
InitTmpRasO, 583 
lnitView(), 610, 709 
lnitVPort(), 553, 610, 709 
Input 

and Intuition, 245, 

block with requester, 203, 

out-of-sync, 920 
Input Device, 245, 246 

input stream, 246 
Input Event, 323 

menus, 176, 

mouse, 266, 

processing menu events, 177 
Input Event Loop, 30 
Input Focus, 78, 248 
Input Handler, 246, 247 
Input Stream, 246 
InputEvent Structure, 246, 321 

ie_Qualifier, 256 
InputPrefs structure, 339 
InputXpression structure, 745 
lnsert(), 492, 498 
InsertCxObJO, 737 

lnstallClipRegion(), 703, 711, 719, 720-721, 723 
Instance, 292 
Instance data, 293, 308 

initializing, 308 
INST_DATA() macro, 309 
INT2, 519 
INT6, 519 
INTB_VERTB, 521 
INTEN Interrupts, 519 
INTENA, 517, 518 

Index 951 

INTENA Register, 517 
INTENAR, 521 

Interconnection class - see icclass 
International Characters 

as menu command keys, 184 
International compatibility, 922 
International strings, 880 

example, 880 

function reference, 883 

functions, 880 



Interprocess communication, 433, 499 
Interrupt stack, 477 

Interrupt Structure, 520, 521 , 521 , 525, 527 
is_Data, 521 , 524, 525 
is_Node, 525 
Interrupts, 917 

68000 interrupt request signals, 517 
68000 priority levels, 517 
autovectors, 518 
deferred, 519 
disable, 520 
disabling, 530 
Exceptions, 473 
handlers, 519, 521 
hardware registers, 517 
non-maskable (NMI), 519 
priorities, 519 
server return value, 525 
servers, 519, 525 
software, 527 
Task private, 473 
INTREQ, 517, 518 
INTREQ Register, 517 
INTREQR, 521 

IntuiMessage structure, 119, 247, 250, 256 
Class, 256-257, 257, 268 
Code, 186, 256, 258, 259-260, 261 , 268 
ExecMessage, 256 
lAddress, 257, 259, 262, 263 
IDCMPWindow, 257 
Micros, 257 

MouseX, 256, 268, 273 
MouseY, 256, 268, 273 
Qualifier, 256, 261,282 
Seconds, 257 
SpecialLink, 257 
IntuiText 

in requester, 204, 
position, 224 
IntuiText structure, 1 23, 1 80, 1 90, 1 91 , 1 92, 21 3, 223, 224, 239,239-240, 
240, 243 
BackPen, 239, 242-243 
DrawMode, 239 
FrontPen, 239-240, 242-243 
IText, 240, 241 
ITextFont, 240, 241 , 243 
LeftEdge, 240, 240 
NextText, 240, 243 
TopEdge, 240, 240 
IntuiTextLengthf), 241 , 243, 244 
Intuition, 619, 927 

3D look, 26 

and other user interface libraries, 24 

BeginRefreshf), 95, 97, 97 

Boopsi - see Boopsi 

Boopsi class reference, 891 

busy pointer, 207 

CloseWindow(), 82 

components of the user interface, 25, 27 

EndRefreshf), 95, 97, 97 

examples 

alert, 221 
blockinput.c, 207 

closewindowsafely.c (for shared IDCMPs), 255 
complex Image drawing, 231 
custom pointer, 275 
easy requester, 217 
input event loop, 31 
IDCMP processing, 251 
Intuition basics (all OS versions), 34 
Intuition basics (Release 2), 32 
Intuition text rendering, 241 
memory functions, 285, 286 
mousetest.c, 269 
raw key processing, 277 
reusing Border structures, 235 
simple Image drawing, 228 
ExtNewWindow structure, 80 
font, 243 

graphics features, 223 
IDCMP, 31 

input event loop, 30, 31 
introduction, 23 



line drawing, 234 

NewWindow structure, 80 

OpenWindow(), 80 

OpenWindowTagList(), 80 

OpenWindowTagsO, 80 

QueryOverscanQ, 86 

struct EasyStruct, 216 

struct Image, 225 

struct IntuiMessage, 256 

struct IntuiText Structure, 239 

struct Menu, 188 

struct Menultem, 189 

struct Remember, 285 

struct Requester, 21 1 

struct Window, 104 

text, 239 
Intuition public classes, 297 
IntuitionBase Structure, 283, 283-284 
INVERSVID, 240, 243, 585 
lnvertString(), 749, 889 
lORequest, 446 

creating, 446 
IPLO, 517 
IPL1, 517 
IPL2, 517 
ISDRAWN, 192 
IsListEmpt, 498 
ISP, 477 
Item Number, 177 

terminator, 177 
ItemAddressO, 177,200 
ITEMENABLED, 175, 191 
ItemFill, 225 
ITEMNUM(), 177, 178 
ITEMTEXT, 190, 191, 192, 225 
itexticlass, 297 
IX structure, 745 
IXSYM_ALT, 745 
IXSYM_CAPS, 745 
IXSYM_SHIFT, 745 
.info file, 345 
JAM1, 234, 237, 239, 242-243, 585 

with INVERSVID, 585 
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JAM1 mode - 

n drawing, 584 
JAM2, 239, 242-243, 585 
JAM2 mode 

in drawing, 584 
Justification 

menu item text, 190 
KCF_ALT, 820-821 
KCF_CONTROL, 820-821 
KCF_DOWNUP, 820 
KCF_SHIFT, 820-821 
KCF_STRING, 820 
KCmpStr(), 890 
KC_NOQUAL, 820-821 
KC_VANILLA, 820-821 
Key Mapping, 277 
Keyboard 

and menus, 176 

as alternate to mouse, 280 

menu shortcuts, 184 

qualifiers, 282 

raw key, 277 

repeat queue limit, 1 08, 114 

Shortcut, 281 , 281 

vanilla key, 277 

with easy requesters, 21 7 
Keyboard Layout, 828 
Keyboard Qualifier, 282 
Keyboard Shortcut - screens, 74 
Keymap, 81 1 

alternate key maps, 821 

AskKeyMap(), 813 

AskKeyMapDefaultQ, 812 

capsable keys, 822 

caveats 

key numbers over hex 67, 818 

dead-class keys, 823 



double-dead keys, 826 

Examples 

AskKeyMapf), 813 

German keymap excerpt, 824 

mapping RAWKEY events to character 

sequences, 814 
mapping text to keypresses, 816 
SetKeyMapO, 813 

high key map, 818 

KCF_ALT, 820-821 

KCF_CONTROL, 820-821 

KCFJDOWNUP, 820 

KCF_SHIFT, 820-821 

KCF_STRING, 820 

KC_NOQUAL, 820-821 

KC_VANILLA, 820-821 

key map standards, 823 

keymapping, 829 

keymapping qualifiers, 819, 820 

keytype table, 820 

low key map, 818 

MapANSI(), 816 

MapRawKey(), 814 

mouse button events, 831 

qualifiers, 820 

repeatable keys, 822 

SetKeyMapO, 813 

SetKeyMapDefault(), 813 

string output keys, 821 

struct KeyMap, 81 2 
KeyMap structure, 812 
keymap. library, 81 1 
KGetChar(), 890 
KGetNum(), 890 
Kickstart version, 435 
KMayGetChar(), 890 
KNOBHIT, 140, 147 
KPrintF(), 890 
KPutChar(), 890 
KPutStr(), 890 
LACE, 545 - 

n View and ViewPort, 548 
Last-In-First-Out (LIFO), 492 
Layer Structure, 214, 284, 704 

bounds, 704 

DamageList, 711, 719 

Flags, 705 

RastPort, 204 
LAYERBACKDROP, 706 
Layerjnfo 

locking, 97 
Layerjnfo Structure, 284, 704, 707, 707-708, 709, 710 
LAYERREFRESH, 261 
Layers, 205, 703, 929 

accessing, 707, 711 

alternative to GimmeZeroZero, 93 

backdrop, 706 

blocking output, 71 1 

clipping rectangle list, 719 

creating, 710, 710 

creating the workspace, 709 

damage list, 97 

deleting, 710 

introduction, 703 

moving, 711 

opening, 706 

order, 71 1 

redrawing, 711 

requester, 204 

scrolling, 71 1 

sizing, 711 

sub-layer operations, 712 

updating, 711 

windows, 170 

with screens, 65 
LAYERSIMPLE, 705 
LAYERSMART, 205, 705 
LAYERSUPER, 705 
Layout 

menu, 179 
LAYOUTA_Spacing, 395 
LayoutMenultemsQ, 376, 413 
LayoutMenultemsAQ, 376, 413 



LayoutMenusQ, 375,413 
LayoutMenusAf), 375, 413 
Left Amiga Key, 184 

with easy requesters, 21 7 

with system requesters, 217 
Left Mouse Button 

selection, 266, 

with alert, 220, 

with menus, 169 
leftmost 

in Gelslnfo, 624 
Length - of Intuition text, 241 
Libraries 

adding, 443 

calling a library function, 437 

Index 953 

relation to devices, 442 

sharing library bases, 467 
Library 

CLOSE vector, 442 

example library source code, 909 

EXPUNGE vector, 442 

OPEN vector, 442 

RESERVED vector, 442 

romtag, 444 
Library (Exec), 435 

Close vector, 437 

Exec 

OpenLibrary(), 435 

Expunge vector, 437 

Library Vector Offset - see LVO 

LVO, 436, 437 

Open vector, 437 

OpenLibraryf), 435 

Reserved vector, 437 

version, 435 
Library structure, 436, 441 
Library Vector Offset - see LVO 
Limits 

change for window, 108, 

message queue, 113, 

window size, 85 
Line 1010 emulator, 474 
Line 1111 emulator, 474 
Line drawing, 588 
Line pattern, 585 
Lines 

and Intuition graphics, 234 

multiple, 589 

patterned, 589 

with Intuition graphics, 223 
LINKLIB macro, 438 
List structure, 490, 520 
Lists 

empty lists, 494 

prioritized insertion, 492 

scanning a list, 494 

searching by name, 493 

shared lists, 497 
LoadRGB4(), 554, 610 
LoadRGB4CM(), 554 
LoadSegO, 479 
LoadViewf), 66, 610, 709 

effect of freeing memory, 560 

in display Viewports, 555 
LocalltemDataO, 790, 810 
Lock, 916, 917 

CloseWorkBench(), 52 

IntuitionBase, 283 

layer info, 97 

layers, 97, 284 

public screen, 50, 51 , 53, 83, 1 08 

public screen list, 54 

window input, 203 
LocklBaseO, 283, 289 
Locking, 473 
LockLayer(), 707, 708 
LockLayerlnfoQ, 707-708, 708 
LockLayersQ, 708 

LockPubScreen(), 50, 51, 53, 53, 54, 56, 59, 75, 76, 83, 108 
LockPubScreenListQ, 54, 76 



Logic equations 

blitter, 596 
Logical And, 719, 722, 722 
Logical Exclusive-Or, 719, 722, 722 
Logical Not, 721,722 
Logical Or, 719, 722, 722 
Long-frame Copper list, 579 
LOWCHECKWIDTH, 182 
LOWCOMMWIDTH, 185 
LVO, 436, 437 
Macros 

menus, 178, 185, 200 
MakeClassQ, 311,330 
MakeDosNode(), 759, 776 
MakeLibrary(), 443 
MakeScreenQ, 66, 70, 76 
MakeVPort(), 66, 555, 610, 709 

allocating memory, 560 

and Simple Sprites, 619 

in double-buffering, 579 
MapANSI(), 816 
MapRawKey(),814 
Masking interrupts, 471 
Master stack, 477 
MatchToolValue(), 354 
Math library, 833 
mathffp. library, 835 
mathieeedoubbas.library, 853 
MathleeeDoubTransBase, 857 
mathieeedoubtrans.library, 857 
mathieeesingbas.library, 845 
MathleeeSingTransBase, 849 
mathieeesingtrans. library, 849 
mathtrans. library, 838 
MAXBODY, 143, 144 
MAXPOT, 142, 143 
MemChunk structure, 463 
MemEntry structure, 460, 461 
MEMF_24BITDMA, 431, 456 
MEMF_ANY, 431,456 
MEMF_CHIP, 14, 227, 274, 288, 431, 456 
MEMF_CLEAR, 21 1 , 431 , 456 
MEMF_FAST, 14,431,456 
MEMFJ_OCAL, 431,456 
MEMF_PUBLIC, 431,456 
MEMF_REVERSE, 431, 456 
MemHeader structure, 462 
MemList structure, 459, 461 
Memory 

allocation, 455 

allocation for BitMap, 552 

allocation with Intuition, 284 

allocation within interrupt code, 457 

AllocMemO, 430, 455 

AllocMem()/Vec() flags, 431 

AllocVecf), 430 

Chip, 431 

Chip memory, 14 

Chip memory (defined), 1 1 

clearing, 456, 592 

deallocation, 455 

deallocation with Intuition, 284 

deallocation within interrupt code, 457 

Fast, 14, 431,456 

Fast (defined), 11 

for area fill, 582 

free, 455, 463 

freeing, 560 
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freeing Workbench screen, 52 

FreeMem(), 431,455 

FreeVecQ, 431 

location of, 456 

loss, 919, 920, 920, 920, 920 

problems, 916 

public, 431,456 

remember key, 285 

Remember Structure, 285 

size 

allocation, 455 

deallocation, 455 



special-purpose chip, 456 
Memory allocation 

Intuition, 284 
Menu, 167 

active window, 79 

Amiga key glyph, 170 

cancelling menu operations, 186 

changing, 175 

checkmark, 182 

command key shortcuts, 281 

custom checkmark, 107 

defined, 29 

disable, 110, 111, 170 

disabling, 175, 185 

double-menu requester, 267 

enable, 170 

Enabling, 185 

Examples 

menu layout, 192, 
simple menu, 172 

flickering, 920 

help, 1 1 1 , 260 

highlighting, 169 

input events, 177 

Items, 168 

layer operation, 712 

layout, 179 

limitations, 170 

linking, 176 

macros, 1 78, 200 

maximum number of menu choices, 170 

menu help, 178, 179 

menu snap, 74 

mouse button, 267 

multi-select, 267 

overview, 167 

positioning, 170 

processing, 171 

processing input events, 178 

right mouse button, 168 

select box, 1 88 

select message, 259 

selection, 267, 268 

setting up, 1 71 

sharing, 176 

standards, 169 

Subltems, 168 

SubMenus, 168 

verify message, 259 

with multiple windows, 171, 176 
Menu Bar, 168 
Menu Help, 111 
Menu Number, 177, 178, 185 

construction, 178 

conversion, 177 

decoding, 178 

disabling, 185 

extraction, 178 

terminator, 177 

valid, 178 
Menu Shortcut, 184 
Menu structure, 179, 188-189, 189-190 

BeatX, 189 

BeatY, 189 

definition, 188 

Firstltem, 189, 189 

Flags, 1 89 

Height, 188 

JazzX, 189 

JazzY, 1 89 

LeftEdge, 1 88, 189 

MenuName, 189 

NextMenu, 188 

TopEdge, 188, 189 

Width, 1 88 
MENUCANCEL, 186 
MENUDOWN, 110,258,268 
MENUENABLED, 189 
MENUHOT, 186 
Menultem structure, 176, 177, 180, 181, 182, 184, 18 

Command, 184, 190, 191 

definition, 189 

Flags, 181, 184,190 



-191,224 



Height, 190 

ItemFill, 180, 190, 191 

LeftEdge, 182,190 

Menultem, 191 

MutualExclude, 182-183, 190 

Nextltem, 189 

NextSelect, 176, 177, 191 

SelectFill, 190, 191, 192 

Subltem, 190 

TopEdge, 190 

Width, 190 
MENUNULL, 176, 177-178, 178, 179, 187, 191,259-260 
MENUNUM(), 177 
MENUSTATE, 186 
MENUTOGGLE, 182, 191 
MENUUP, 110, 186, 187,258,268 
MENUWAITING, 186 
Message Port, 446 

creation, 446, 501 

deletion, 501 

IDCMP, 249 

Intuition, 247 

public, 501 
Message Queue 

IDCMP, 250 
Message Structure, 250, 694 
Messages, 499 

discarded by Intuition, 113 

emergency, 220 

Examples 

skeleton of waiting for a signal, 434 

GetMsgO, 434 

getting, 505 

IDCMP, 90 

interprocess communication, 433 

mouse, 268 

putting, 503 

queue limits, 113 

replying, 505 

waiting for, 504 

waiting for messages and signals, 435 

Index 955 

Messages arrival action, 500 
Messages (Boopsi), 293 

final, 309, 

interim, 309 
Methods, 293 
MIDDLEDOWN, 258 
MIDDLEUP, 258 
MIDRAWN, 189 
MinList structure, 489 
MinNode structure, 488 
Minterm, 596 
Modal requesters, 202 
Mode ID 

of alert screen, 220 
ModelD, 545, 550, 563, 565 

Displaylnfo, 567, 

MonitorSpec, 568 
modelclass, 302 
ModeNotAvailable(), 568, 611 
Modes 

display, 536, 545, 

ViewPort, 545, 550 
Modify Clipping Region, 719 

ModifylDCMPf), 107, 188, 211, 216, 219, 249-250, 253-254,257,264,264 
ModifyPropQ, 166 
Modulo, 595 

MonitorSpec structure, 568 
Monochrome Screen 

and Intuition graphics, 225 
Mouse 

basic activities, 265 

button usage, 266 

click, 265 

combining buttons and movement, 268 

double click, 265 

drag, 265 

dragging, 268 

enable reporting, 109 

hot spot, 266 



keyboard as alternate, 280 

left (select) button, 266 

menu button, 267 

message queue limit, 1 1 4 

move, 265 

movement coordinates, 268 

position in GimmeZeroZero, 93 

position relative to window, 105 

position reporting, 114 

press, 265 

queue limits, 108,268 

right (information transfer) button, 267 

with alert, 220 
Mouse button 

right, 175 
Mouse button events, 831 
Mouse Movement 

enable events, 273 
Mouse Position 

message, 256 
Move(), 588, 61 1 , 674 
MOVEC, 517 
Movel_ayer(), 708, 71 1 
MoveLayerlnFrontOfQ, 708, 711 
MoveScreen(), 40, 74, 76 
MoveSizeLayerQ, 711 
MoveSpritef), 288, 620, 668 
MoveWindow(), 112, 115 
MoveWindowlnFrontOfQ, 112, 113, 115 
MrgCop(), 66, 610, 709 

in graphics display, 555 

installing VSprites, 628 

merging Copper lists, 560 
Msg structure, 303, 307 
MsgPort structure, 500 

SigTask, 254 
MSP, 477 

Multiple Asynchronous lORequests, 449 
Multiple Gadgets 

in easy request, 217 
Multiple Select 

menu, 169, 267, 

menu processing, 176 
Multiple Tasks 

with layers, 707 
Multitasking, 429 
Mutual Exclude 

menu, 168, 181, 182, 

menu item, 190 
Mutual exclusion, 473 
myl_abelLayer(), 712 
NBU_NOTIFY, 743 
NBUJJNIQUE, 743 
Nested Disabled Sections, 530 
New Look, 55 

SA Pens, 47, 

screen, 42 
NewBroker structure, 730 
NewGadget structure, 379 
NewLayerlnfo(), 710 
NewList(), 491 
NEWLIST, 498 
NewList(), 498, 887 
NewMenu structure, 370 
NewModifyProp(), 147, 148, 166 
NewObject(), 295, 330 
NewObjectA(), 294, 330 
NewRegion(), 720, 722 
NewScreen 

SPRITE flag, 619 
NewScreen Structure, 42, 43, 46 
NewWindow structure, 80, 106, 352 

BitMap, 1 1 1 

BlockPen, 106 

CheckMark, 107 

DetailPen, 106 

extended new window structure, 80 

FirstGadget, 107 

flags, 109-111 

Height, 106 

IDCMPFIags, 107 

LeftEdge, 1 06 

MaxHeight, 108 



MaxWidth, 108 

MinHeight, 108 

MinWidth, 108 

Screen, 107 

Title, 107 

TopEdge, 106 

Type, 1 07 

Width, 106 
Next 

in ViewPort structure, 553 
NEXTNODE, 498 
NextPubScreenQ, 54, 76 
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NMI, 519, 519, 525 
NMI Interrupts, 519, 525 
NM_BARLABEL, 371 
NM_END, 370 
NMJTEM, 370 
NMJTEMENABLED, 371 
NMJvlENUENABLED, 371 
NM_SUM, 370 
NM_TITLE, 370 
Node structure, 488 

Inname, 54, 

ln_Pri, 525, 527 
Nodes 

initialization, 489 

inserting, 491 

priority, 489 

removing, 491 

successor and predecessor, 488 

text names, 489 

type, 489 
NO_ICON_POSITION, 352 
NOISYREQ, 203, 213 
NOITEM, 177, 179, 185 
NOMENU, 177 

NOREQBACKFILL, 204, 213-214 
NOSUB, 177, 179, 185 
Notification 

use by preferences, 336 
Notify 

close requester, 210, 

open requester, 21 
NS_EXTENDED, 43, 45, 46 
NTJNTERRUPT, 527 
NT_SOFTINT, 527 
O-Pen - see AOIPen 
Object, 292 

Object Oriented Programming - see Boopsi 
Object Oriented Programming System for Intuition - see Boopsi 
ObtainConfigBinding(), 759 
ObtainGIRPortO, 319, 323, 330 
ObtainSemaphoreO, 512, 513, 513, 514, 514, 515 
ObtainSemaphoreList(), 510, 514, 515 
ObtainSemaphoreSharedO, 513, 515 
OFF_DISPLAY, 610 
OffGadget(), 130, 166 
OffMenuf), 185, 189, 191,200 
OM_ADDMEMBER, 302, 307 
OM_ADDTAIL, 307 
ONJ3ISPLAY, 610 
OMJ3ISPOSE, 307 

see also Appendix B and DisposeObject() 
OMJ3ET, 307, 311 

see also Appendix B and GetAttr() 
OM_NEW, 307, 308 

see also Appendix B and NewObject() 
OM_NOTIFY, 307, 309 
OM_REMMEMBER, 307 
OM_REMOVE, 307 
OM_SET, 305, 307, 309 

Boopsi gadgets, 298 

see also Appendix B and 

SetAttrs()/SetGadgetAttrs() 
OMJJPDATE, 307, 309 

Boopsi gadgets, 298 
OnGadget(), 130,166 
OnMenuf), 185, 189, 191,200 
Open vector, 437 
OpenQ, 263 



OpenClipboardf), 781,810 

OpenDevice(), 447 

OpenDiskFont(), 188, 243, 670, 675 

OpenFont(), 243, 670, 675 

OpenlFF(), 344, 782, 810 

Opening a device, 447 

Openl_ibrary(), 3, 4, 188, 263, 435 

OpenMonitorj), 568, 611 

OpenScreen(), 42, 43, 45, 46, 76 

OpenScreenTagList(), 42, 45, 45, 46, 53, 56, 59, 76 

OpenScreenTagsf), 42, 42, 45, 46, 76 

OpenWindow(), 80, 115 

OpenWindowTagListO, 53, 80, 82, 83, 85, 90, 92, 92, 93, 97, 98, 104, 

107, 108, 115, 175,249,254 
OpenWindowTags(), 80, 115 
OpenWorkBenchQ, 52-53, 76 
opGet structure, 31 1 
opMember structure, 303 
opSet structure, 305, 308 
Optimized Refresh 

layers, 705, 711,719 
OPUFJNTERIM, 309 
opUpdate structure, 309 
OrRectRegionQ, 722 
OrRegionRegion(), 722 
OSCAN_MAX, 62 
OSCAN_STANDARD, 62 
OSCAN_TEXT, 62, 86 
OSCAN_VIDEO, 62 
OSERR_NOCHIPMEM, 45 
OSERR_NOCHIPS, 45 
OSERR_NOMEM, 45 
OSERR_NOMONITOR, 45 
OSERR_PUBNOTUNIQUE, 45 
OSERRJJNKNOWNMODE, 45 
Outline mode 

in Flood() fill, 591 
Outline pen, 584 
Output 

and Intuition, 245, 248 

and the console device, 248 

and the graphics library, 248 



Overscan 



autoscroll, 74 

cloning, 59 

coordinate reference, 46 

display clip, 49, 61 

effect on the Viewing Area, 533 

finding display clip, 63 

maximum, 62 

maximum custom value, 62 

preference, 62 

preset values, 62 

QueryOverscan(), 59 

restrictions, 66 

SA_DCIip, 49, 62 

SAOverscan, 49 

screen dimensions, 46 

screen offsets, 46 

standard, 49, 62 

text, 46, 62 

video, 62 

VideoControlQ, 63 

ViewPortExtra Structure, 63 

visible area, 63, 86 
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OverscanPrefs structure, 339 

OwnBlitterf), 599, 599, 612 

ParentChunk(), 789, 810 

ParselFFQ, 344, 782, 810 

ParselXQ, 746 

PA_SOFTINT, 527 

Paula, 11,517 

PC, 518 

Pens 

and Intuition text, 239 
background, 58 
block, 47, 57, 106 
compatible, 55 
custom, 56 
detail, 47, 57, 106 



Drawlnfo, 1 06 

fill, 58 

from public screen, 56 

highlight text, 58 

in Border structure, 238 

Intuition text, 242 

monochrome, 55 

new look, 55 

SA Pens, 47 

screens, 59 

shadow, 58 

shine (highlight), 58 

text, 57 

text on fill, 58 

with graphics, 85 

Workbench, 57 
Performance 

loss of, 920, 920 
PermitO, 110,470,480,520 
PFBA, 545 

in dual playfield mode, 547 
PGAFreedom, 392, 394 
Philosophy, 23 
Pixel width, 548 
PlaneOnOff 

in Image structure, 226, 

using, 230 
PlanePick 

in Image structure, 226, 

using, 230 
PLANEPTR, 552 
Pointer, 272 

active window, 79 

ClearPointer(), 274 

color, 274 

custom, 273 

data definition, 274 

default, 114 

hot spot, 266, 274 

keyboard control, 280 

position, 114, 272 

resolution, 272 

set, 114, 273 

SetPointer(), 273, 274 
Pointer Relative 

requester, 206 
POINTREL, 205-206, 210, 212, 213 
PolyDraw(), 589, 611 
Polygons, 589 
PopChunkQ, 787, 810 
POPPUBSCREEN, 52, 83 
Port, 499 

named, 502, 

rendezvous at, 502 
PORTS, 519, 525, 526 
PORTS Interrupts, 519, 525 
Position 

border, 234 

Intuition graphics, 224 

Intuition text, 240 

of Image structure, 226 

screen, 40 

window, 106 
PRED, 498 

PREDRAWN, 212, 213, 214 
Preemptive Task Scheduling, 518 
Preferences, 25, 331 , 929 

AlloclFFO, 344 

CloselFF(), 344 

CurrentChunk(), 344 

editor (IControl), 75 

EndNotifyO, 336, 344 

ENVARC:sys, 335 

ENVisys, 335 

examples 

prefnotify.c, 336, 
showprefs.c, 341 

file format (2.0), 337, 340 

FindPropO, 344 

font, 48, 58, 59, 85, 179-180 

FreelFFf), 344 

GetDefPrefs(), 332, 344 

GetPrefsf), 332, 344 



IControl, 281 

IDCMP_NEWPREFS, 262, 332 

IFF chunks, 338 

InitlFFasDOSO, 344 

introduction, 25 

Intuition, 75, 281 

notification, 336 

OpenlFF(), 344 

overscan, 40, 59, 62 

palette, 47 

ParselFFQ, 344 

pointer, 274 

printer device, 334 

PropChunk(), 344 

public screens, 83 

reading (1.3), 332 

reading (2.0), 335 

screen data, 59 

SetPrefsQ, 334, 344 

setting (1.3), 334 

setting (2.0), 335 

StartNotify(), 336, 344 

struct FontPrefs, 338 

struct IControlPrefs, 338 

struct InputPrefs, 339 

struct Overscan Prefs, 339 

struct Preferences (1 .3), 333 

struct PrefHeader, 337 

struct PrinterGfxPrefs, 339 

struct PrinterTxtPrefs, 340 

struct ScreenModePrefs, 340 

struct SerialPrefs, 340 
Preferences structure (1 .3), 333 
PrefHeader structure, 337 
PrinterGfxPrefs structure, 339 
PrinterTxtPrefs structure, 340 
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printf(), 887 

PrintlText(), 224, 224, 240, 240, 243, 244 

Private class, 293 

Privilege violation, 474 

Process, 430 

Process structure, 430, 434 

pr_WindowPtr, 21 9 
Processes, 466 
Processor 

interrupt priority levels, 471 
Productivity Mode, 537, 561 
Programming guidelines, 13 
PROPBORDERLESS, 140, 147 
PropChunkQ, 344, 783, 810 
propgclass, 297 
Proplnfo structure, 147 
PROPNEWLOOK, 140, 147 
PSNF_PRIVATE, 54 
Public class, 293 
Public memory, 431 , 456 
Public Screen, 52, 53 

access by name, 83 

accessing, 50 

and Intuition graphics, 225 

cloning, 59 

closing, 53 

copying pens, 56 

default, 52, 59, 82 

display clip, 59 

example, 56, 83 

font, 59 

get default, 50 

global modes, 52, 83 

jumping, 83 

list, 54 

locking, 50, 51 

making private, 53 

making public, 53 

mode, 59 

name, 49, 53 

name collision, 45 

next, 54, 83 

notification, 49, 53 

POPPUBSCREEN, 52, 83 



requesters, 219, 219 

set default, 50 

SHANGHAI, 52, 83 

sharing, 65 

status, 53 

structures, 54 

visitor window, 82 

WAPubScreen, 108 

WAPubScreenFallBack, 108 

WAPubScreenName, 1 08 

window fallback, 83 

windows on, 77, 82 

Workbench, 52 
PUBLICSCREEN, 108 
PubScreenNode Structure, 54 

InName, 54 

psnFlags, 54 

psnNode, 54 

psnScreen, 54 
PubScreenStatusO, 53, 76 
PushChunk(), 787, 810 
putcharQ, 887 
PutDefDiskObject(), 353 
PutDiskObjectO, 353 
PutMsgf), 503, 520 
puts(), 887 
QBIitQ, 599, 612 

linking bltnodes, 600 
QBSBIitQ, 599, 612 

avoiding flicker, 600, 

linking bltnodes, 600 
Qualifier, 281-282 

Alt, 282 

Amiga, 282 

Caps Lock, 282 

Ctrl, 282 

mouse button, 282 

numeric pad, 282 

repeat, 277, 282 

Shift, 282 
Quantum, 430 

QueryOverscan(), 59, 63, 76, 86 
Queue Limit, 113 

IDCMPJJPDATE, 277 

keyboard repeat, 1 08 

mouse, 108 

mouse move, 268 

raw key, 277 

vanilla key, 277 
Queues, 492 
QuicklO, 448 
Quiet 

screen, 49 
RangeRand(), 887 
Raslnfo, 550 

Raslnfo Structure, 70, 552 
RASSIZEQ, 610 
RASSIZE() macro, 551 
Raster 

allocation, 98 

depth, 544 

dimensions, 549 

in dual-playfield mode, 545 

memory allocation, 551 

one color, 593 

Raslnfo structure, 550 

scrolling, 593 
RastPort 

and Windows, 587, 

Area buffer, 582, 

pointer to, 587, 

pens, 584 
RastPort Structure, 39, 58, 64, 65, 85, 224, 224, 225,227, 230, 235, 240, 

243,581,669,670,704,710 

in layers, 704 
Raw Key, 277 

codes, 90, 

queue limit, 277 
RawDoFmt(), 217 
RawKeyConvert(), 262, 277 
RBF Interrupts, 519 
RBFHandler, 523 
RDB - see RigidDiskBlock 



ReadChunkBytesf), 810 
ReadChunkRecordsQ, 810 
ReadPixelO, 588, 61 1 
RECOVERY_ALERT, 220, 221 
Rectangle fill, 591 
Rectangle scrolling, 593 
Rectangle Structure, 62, 676, 721 
with regions, 720 

Index 959 

RectFillO, 591,611 
Refresh 

disable reporting, 97, 110 

events with smart refresh, 110 

layers, 705, 711 

locking layers, 97 

optimized window, 97 

simple refresh, 705 

smart refresh, 705 

super bitmap, 706 

window notification, 97 
RefreshGadgetsO, 97, 166 
RefreshGList(), 128, 130, 166 
RefreshWindowFrameO, 97, 115 
Regions, 703 

changing, 722 

clearing, 722 

creating, 720 

for clipping, 93 

removing, 720 
Register parameters, 521 
Register usage conventions, 6 
Release 2 

extensions, 18, 

migrating to, 18, 

versus 1.3, 19 
ReleaseConfigBinding(), 759 
ReleaseGIRPortf), 323, 330 
ReleaseSemaphore(), 513, 514, 515 
ReleaseSemaphoreList(), 514, 515 
RemakeDisplayO, 66, 76 
Remap Coordinates, 703 
RemBob(), 641,668 

Remember Structure, 284, 284-285, 285, 285-286 
REMHEAD, 498 
RemHeadf), 492, 498, 520 
REMHEADQ, 498 
RemlBob(), 641,668 
RemlntServer(), 525 
REMOVE, 494, 498 
Remove(), 492, 498 
RemoveClass(), 312,330 
RemoveCxObji), 737 
RemoveGadgetO, 1 66 
RemoveGListO, 122, 166, 322 
RemPort(), 502 
RemSemaphoreO, 513, 515 
REMTAIL, 498 
RemTailO, 492, 498, 520 
RemTaskQ, 469, 480 
RemTOF(), 888 
RemVSpriteO, 627, 668 
Render 

border, 235, 

requesters, 204 
Repeat Qualifier, 277 
Replying, 499, 505 
ReplyMsg(), 249, 253, 263, 505, 520 
ReportMouse(), 114, 268, 273, 282 
REQACTIVE, 214 
REQOFFWINDOW, 214 
Request(), 1 1 2, 202, 203, 21 1 , 222 
Requester - see ASL 

advantages over menus, 170 

andthelDCMP, 211 

clear message, 260 

count for window, 105 

defined, 30 

direct rendering, 205 

disabling system requesters, 219 

double menu, 202, 203, 210, 211 

easy requester, 215 



ending, 204 

file, 20 

font, 20 

initialization, 21 1 

limits, 204 

low level use of easy request, 218 

modal, 202 

multiple, 204 

pointer relative, 210 

position in GimmeZeroZero, 93 

positioning, 205, 212 

refreshing, 205 

rendering, 204 

set message, 260 

system requester, 219 

text in easy requester, 215 

title in easy requester, 216 

true, 202 

verify message, 260 
Requester Structure, 204, 21 1-212, 224, 235 

Backfill, 204, 213, 214 

Flags, 210, 212, 213, 214 

Height, 212 

ImageBMap, 205, 213, 214 

LeftEdge, 205, 210, 212 

OlderRequest, 212 

RelLeft, 206, 210, 212 

RelTop, 206, 210, 212 

ReqBorder, 212 

ReqGadget, 212 

Reqlmage, 213,214 

ReqLayer, 205, 214 

ReqPad1,214 

ReqPad2, 214 

ReqText, 213 

RWindow, 214 

TopEdge, 205, 210, 212 

Width, 212 
Reserved vector, 437 
ResetMenuStripQ, 111, 175, 176,200 
Resident structure, 444 
Resolution 

pointer position, 272 
Restricting Graphics 

with layers, 710 
RethinkDisplayO, 66, 70, 76 
RHeight, 549 
Right Amiga Key, 184 

with Alt key, 1 76 
Right Justification 

menu item text, 190 
Right Mouse Button 

cancel window drag, 77 

cancel window sizing, 78 

disable menu, 110 

information transfer, 266 

trap, 268 

with alert, 220 
rightmost 

960 Amiga ROM Kernel Reference manual: Libraries 

in Gelslnfo, 624 
RigidDiskBlock, 769 
RigidDiskBlock specification, 770 
RINGTRIGGER, 659 
romtag, 444 
rootclass, 292, 297 
RouteCxMsg(), 746 
RTE, 521 
RTS, 521 , 525 
RWidth, 549 
RxOffset 

effect on display, 549 

in Raslnfo structure, 550 

in ViewPort display memory, 549 
RyOffset 

effect on display, 549 

in Raslnfo structure, 550 

in ViewPort display memory, 549 
SA_AutoScroll, 49, 63 
SABehind, 49 
SA_BitMap, 48 



SABIockPen, 47 

SA Colors, 47 

SA_DCIip, 49, 62, 62, 63 

SA_Depth, 47 

SADetailPen, 47 

SA_DisplaylD, 45, 47, 59 

SAErrorCode, 45, 46 

SA_Font, 47, 58, 85 

SAJ=ullPalette, 47 

SAJHeight, 46 

SA_Left, 40, 46 

SAOverscan, 49, 62, 63 

SA_Pens, 47, 55, 56-57 

SA PubName, 49, 53 

SA_PubSig, 49, 53 

SA_PubTask, 49, 53 

SA_Quiet, 49 

SA_ShowTitle, 49 

SA_SysFont, 48, 58, 59 

SA_Title, 47 

SA_Top, 40, 46 

SAJType, 48-49 

SA_Width, 46 

ScalerDiv(), 598 

Screen Structure, 40, 45, 54, 58, 82, 108, 235 

1.3 compatible usage, 19 

BarLayer, 40 

BitMap, 40 

BlockPen, 55 

DetailPen, 55 

Font, 41,58, 215 

Layerlnfo, 40 

LeftEdge, 40, 86 

MouseX, 40 

MouseY, 40 

RastPort, 40 

TopEdge, 40, 86 

UserData, 41 

ViewPort, 40, 64 

WBorBottom, 40, 89 

WBorLeft, 40, 89 

WBorRight, 40, 89 

WBorTop, 40, 89 
SCREENBEHIND, 49 
ScreenModePrefs structure, 340 
SCREENQUIET, 49 
Screens 

aspect ratio, 20 

autoscroll, 74 

attributes, 46 

color selection, 47, 65 

CON: on, 20 

coordinate reference, 46 

data structures, 39 

defined, 27 

display modes, 20, 37 

DisplayBeepO, 75 

Examples 

cloning a public screen, 59 
double buffered screen, 67 
dual playfield screen, 70 
finding the Workbench screen, 51 
opening a new look screen, 42 
opening screens compatibly, 44 
using a public screen, 56 

font, 59 

from window, 105 

hide title, 92 

menu snap, 74 

mode for alert, 220 

MoveScreen(), 74 

multiple screens, 38 

positioning, 40 

ShowTitleO, 65 

tag items, 46 

title bar, 49, 65, 75 

using layers with, 65 

Workbench, 75 
ScreenToBackf), 74, 76 
ScreenToFront(), 74, 76 
Scrolling 

a RastPort, 593 

auto screen, 49 



keyboard qualifiers, 74 

screens, 63, 74 
ScrollLayer(), 98, 706, 707-708, 71 1 
ScrollRaster(),261,593, 612 
ScrollVPortO, 552 
Select Box 

menu, 188, 

menu item, 190 
Select Button 

with menus, 169 
SELECTDOWN, 258, 268 
SelectFill, 225 
Selection - menus, 169 
SELECTUP, 258, 268 
Self-modifying code, 478 
Semaphores, 473, 51 

function prototype summary, 510 
Sending A Command To A Device, 448 
SendlO(), 448, 449, 520 
Serial device, 925 
SerialPrefs structure, 340 
SetAfPtf), 585, 611 
SetAPenQ, 584, 611,672 
SetAttrsO, 295, 330 
SetBPenQ, 584, 611,672 
SetCollision(), 647, 668 
SetCurrentBinding(), 759, 776 
SetCxObjPri(), 737 
SetDefaultPubScreen(), 50, 76 

Index 961 

SetDMRequestO, 210, 222 
SetDrMd(), 585 
SetDrMode(), 611,672 
SetDrPt(), 585, 589, 611 
SetEditHookQ, 166 
SetExcept(), 473 
SetFilter(), 746 
SetFilterlXQ, 746 
SetFont(), 670 
SetFunction(), 442 
SetGadgetAttrs(), 295, 305, 330 
SetlntVector(), 518, 521 
SetKeyMapf), 831 
SetKeyMapDefault(), 813 
SetLocalltemPurgef), 799, 810 
SetMenuStrip(), 1 1 1 , 1 71 , 1 75, 1 76, 200 
SetMouseQueuef), 114, 269, 282 
SetOPenQ, 584, 611 
SetPointer(), 114, 115, 273, 274, 282 
SetPrefs(), 262, 289, 289, 334, 344 
SetPubScreenModes(), 52, 76, 83 
SetRastf), 593, 612 
SetRexxVarf), 888 
SetRGB4(), 275 
SetRGB4CM(), 554, 610 
SetSignal(), 433, 484, 485 
SetSoftStyleO, 675 
SetSRQ, 478 
SetSuperAttrs(), 330, 890 
SetTaskPri(), 469, 480 
SetTranslate(), 742 
SetWindowTitlesQ, 107, 113, 115 
SetWrMask(), 61 1 
SGA_BEEP, 160, 161 
SGA_END, 160, 161, 161 
SGA_NEXTACTIVE, 160, 161 
SGA_PREVACTIVE, 160, 161 
SGA_REDISPLAY, 160, 161, 161 
SGA_REUSE, 160, 161, 161 
SGAJJSE, 160, 161, 161 
SGH_CI_ICK, 158, 161, 161 
SGH_KEY, 158, 160, 161 
SGM_EXITHELP, 158 
SGM_FIXEDFIELD, 158 
SGMJMOFILTER, 158 
SGM_REPLACE, 157 
SGWork structure, 159 
SHADOWPEN, 58, 238 
SHANGHAI, 52, 83 
Share 

IDCMP, 254 



Share Display, 703 

layers, 703 
Sharing 

of layers, 707 
Shift Select, 267 
SHIFTITEM(), 200 
SHIFTMENU(), 200 
SHIFTSUB(), 200 
SHINEPEN, 58, 238 
Shortcut, 184 

Short-frame Copper list, 579 
SHOWTITLE, 49 
ShowTitleO, 49, 65, 75, 76, 92 
Signal)), 484, 485, 520 
Signal bit 

IDCMP, 254 
Signal bit number, 500 
Signal Semaphore, 510 
Signals, 432 

allocation, 482 

coordination, 481 

exception, 473 

IDCMP, 250 

on arrival of messages, 500 

waiting for, 482 

waiting for messages and signals, 435 
Simple Refresh 

attribute, 110, 

requester, 205 
Simple Refresh Layer, 705 
Simple Refresh Window, 94 
Simple Sprite 

allocation, 619 

colors, 618 

and Viewports, 618 

functions, 619 

GfxBase, 632 

in Intuition, 619 

position, 617 

simple definition, 614 
SIMPLEREQ, 205 
SimpleSprite structure, 617 
Single-buffering, 550 
Size 

by inner dimension, 108 

change window limits, 108 

enable gadget, 109 

window auto-adjust, 1 1 1 
Size Gadget 

cancel window sizing, 78, 

window, 78 
Size Limits 

window, 108 
SizeLayer(), 706, 708, 711 
SizeWindowQ, 112, 115 
Sizing 

of layer, 705, 

window limits, 89 
Smart Refresh 

attribute, 110, 

refresh events, 110, 

requester, 205 
Smart Refresh Layer, 705 
Smart Refresh Window, 94 
SOFTINT Interrupts, 519 
Software error, 474 

Software interrupts, 499, 500, 517, 519, 527 
SortGListO, 642, 668 

ordering GEL list, 628 
SprColors 

changing VSprites, 627 
SprColors pointer 

in VSprite structure, 626 

in VSprite troubleshooting, 632 
sprintf(), 887 
Sprite 

and Intuition, 288 

color, 546 

data definition, 274 

display, 543 

in animation, 555 

in Intuition windows & screens, 288 

pairs, 61 8 



reserving, 632 
Sprite Animation 

introduction, 614 
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Sprite DMA, 633 
spriteimage 

structure, 620 
SPRITES, 545-546 
sprRsrvd Gelslnfo member 

in reserving Sprites, 632 
SSP, 477 
Stack, 477 

Interrupt stack, 477 

ISP, 477 

Master stack, 477 

MSP, 477 

overflow, 91 6 

SSP, 477 

Supervisor stack, 477 

User stack, 477 

USP, 477 
Stack overflows, 469 
Stack size, 352 
Standards 

menus, 169 
StartNotifyO, 336, 344 
Startup-sequence, 933 
STDSCREENHEIGHT, 46, 62 
STDSCREENWIDTH, 46, 62 
StopChunk(), 783,810 
StopOnExit(), 785, 810 
StoreltemlnContextO, 791, 810 
Storel_ocalltem(), 791,810 
Strap, 925 
strgclass, 297 
STRINGA_ExitHelp, 387 
STRINGA_Justification, 387 
STRINGA_ReplaceMode, 387 
StringExtend structure, 157 
Stringlnfo structure, 155 
struct Gadgetlnfo, 316 
Structures 

access to global system structures, 470 

AnimComp, 652 

AnimOb, 652 

AvailFonts, 688 

AvailFontsHeader, 688 

bltnode, 600 

Bob, 635 

Boollnfo, 139 

Border, 123 

Class, 305 

CollTable, 646 

ColorFontColors, 698 

ColorTextFont, 697 

ConfigDev, 756 

ContextNode, 789 

CurrentBinding, 759 

DBufPacket, 645 

DiagArea, 761 

DiskFontHeader, 699 

DosEnvc, 760 

EasyStruct, 21 6 

ExpansionRom, 757 

FileRequester, 416 

FontContents, 698 

FontContentsHeader, 698 

FontPrefs, 338 

FontRequester, 422 

Gadget, 132 

Gadgetlnfo, 316, 318 

gpGolnactive, 322 

gpHitTest, 320 

gplnput, 320 

gpRender, 319 

Hook, 312 

IControlPrefs, 338 

IFFHandle, 780 

Image, 225 

InputEvent, 321 

InputPrefs, 339 



InputXpression, 745 

IntuiMessage, 119, 256 

IntuiText, 123,239 

IX, 745 

Keymap, 812 

Library, 436, 441 

Menu, 188 

Menultem, 189 

Message, 694 

Msg, 303, 307 

NewBroker, 730 

NewGadget, 379 

NewMenu, 370 

opGet, 31 1 

opMember, 303 

opSet, 305, 308 

opUpdate, 309 

OverscanPrefs, 339 

Preferences (1.3), 333 

PrefHeader, 337 

PrinterGfxPrefs, 339 

PrinterTxtPrefs, 340 

Process, 430, 434 

Proplnfo, 147 

RastPort, 581 , 669, 670 

Rectangle, 676 

Remember, 285 

Requester, 21 1 

ScreenModePrefs, 340 

SerialPrefs, 340 

SGWork, 159 

shared, 470 

StringExtend, 157 

Stringlnfo, 155 

Task, 430, 465 

TAvailFonts, 689 

TextAttr, 671 , 682 

TextExtent, 676 

TextFont, 674, 681 , 694 

TextFontExtension, 681 , 683, 696 

TFontContents, 699 

TTextAttr, 682 

Window, 104 
Stub, 438 
subclass, 292 
Subltems 

number, 177, 

number terminator, 177 
SUBNUMQ, 177 
SUCC, 498 

SuperBitMap theory, 706 
SuperBitMap Layer, 705 

Index 963 

SuperBitMap Refresh 

attribute, 1 1 1 

creating, 98 

description, 96 

memory requirements, 96 

update responsibility, 96 
SuperBitMap Window, 94 

example, 99 
superclass, 292 
SUPERHIRES, 545 
Supervisor Modes, 475, 477, 518, 520 
Supervisor stack, 477 
SwapBitsRastPortClipRect(), 712 
Synchronization 

of layers, 707 
SyncSBitMapQ, 98 
SysBase Structure, 521 
sysiclass, 297 

SysReqHandler(), 217, 218-219 
SYSREQUEST, 214 
SysRequestHandler(), 222 
System)), 20 
System Request 

easy requester, 219 
System stack, 475, 520 
TADeviceDPI, 682 
Tag lists 

copying, 871 



creating, 871 

filtering, 872 

mapping, 874 

reading, 873 

boolean, 874 

random access, 874 

sequential, 873 
Tagltem Structure 

ti_Data, 45, 1 08 
Tagltems - screen, 46 
Tags, 867 

advanced use, 871 

function reference, 883 

functions, 868 

simple example, 869 

simple usage, 868 

structures, 867 

with open screen, 43 

with OpenWindowQ, 80 
Task signal, 499 
Task Structure, 49, 430, 465 
Task-Relative Interrupts, 517 
Tasks, 429, 430, 917 

cleanup, 469 

communication, 481 

coordination, 481 

creation, 466, 467 

stack, 466 

exclusion, 470 

deallocation of system resources, 469 

finalPC, 469 

forbidding, 470 

initialPC, 469 

non-preemptive, 470 

priority, 469 

sharing library bases, 467 

stack 

minimum size, 468 
overflows, 469 
supervisor mode, 468 
user mode, 468 

switching, 932 

termination, 469 
TAvailFonts structure, 689 
TBE Interrupts, 519 
tc_MemEntry, 461 
Terminal 

virtual, 77 
Testing, 922 
Text(), 670 
Text 

about Amiga fonts, 669 

and Intuition graphics, 239 

AskSoftStyle(), 675 

aspect ratio, 681 , 682 

AvailFontsO, 688 

AvailFonts flags, 689 

Caveats 

don't assume Topaz-8, 672 

ClearEOLQ, 675 

ClearScreen(), 675 

cloning a RastPort, 673 

color fonts, 697 

ColorTextFont flags, 697 

COMPLEMENT, 673 

Compugraphic fonts, 670, 681 , 682, 683 

dots per inch, 682 

drawing modes, 672 

Examples 

list available fonts, 690 
measuring and fitting text, 678 
render a text file to a window, 684 
sample font source, 699 
skeleton for opening a font, 671 
skeleton for selecting aspect ratio, 683 
skeleton for soft styling a font, 675 
skeleton using AvailFontsO, 689 

ExternFontO, 682 

font bitmaps, 695 

font flags, 671 

font preferences, 671 

font scaling, 670, 681 

font style flags, 671 



FontContentsHeader file IDs, 698 

FontExtent(), 676 

format of a font file, 698 

in easy requester, 21 5 

in requester gadgets, 206 

Intellifont engine, 670 

INVERSEVID, 673 

JAM1,672 

JAM2, 673 

kerning, 696 

length, 241 

making the text fit, 676 

menu item, 169, 190 

Move(), 674 

OpenDiskFontf), 670, 675 

OpenFont(), 670, 675 

outline fonts, 670, 682, 683 

rendering the text, 673 

selecting a font, 670 

SetAPen(), 672 

SetBPenf), 672 

SetDrModeO, 672 

SetFont(), 670 

SetSoftStyleO, 675 
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setting the font style, 675 

struct AvailFonts, 688 

struct AvailFontsHeader, 688 

struct ColorFontColors, 698 

struct ColorTextFont, 697 

struct DiskFontHeader, 699 

struct FontContents, 698 

struct FontContentsHeader, 698 

struct Message, 694 

struct RastPort, 669, 670 

struct Rectangle, 676 

struct TAvailFonts, 689 

struct TextAttr, 671 , 682 

struct TextExtent, 676 

struct TextFont, 674, 681 , 694 

struct TextFontExtension, 681 , 683, 696 

struct TFontContents, 699 

struct TTextAttr, 682 

Text(), 670 

TextExtentf), 676 

TextFitQ, 676 

TextLengthQ, 676 

with Intuition graphics, 223 
Text structure 

1.3 compatible usage, 19 
TextAttr Structure, 47, 58, 240, 243, 671 , 682 
TextExtentf), 676 
TextExtent structure, 676 
TextFitQ, 676 

TextFont Structure, 58, 674, 681, 694 
TextFontExtension structure, 681 , 683, 696 
TextLength(), 676 
TEXTPEN, 57 
TFCHJD, 698 

TFontContents structure, 699 
Time 

getting current values, 288 
TimeDelayO, 888 
Timer device, 926 
Title 

active window, 79 

font, 107 

screen, 47 

screen (from window), 107 

window, 107 
Title Bar 

hidden (screen), 49 

menus, 168 

screens, 39, 49, 75 

window, 89 
TmpRas, 583 
ToolTypes 

array, 354 

DONOTWAIT, 354 

parsing, 354 

standard, 354 



STARTPRI, 354 

TOOLPRI, 354 
topmost 

in Gelslnfo, 624 
Trace, 474 
Trackdisk 

problems, 921 
Trackdisk device, 926 
Translate)), 865 

output buffer, 866 
Translator library, 865 

exception rules, 866 
TRAP 

address error, 474 

bus error, 474 

CHK instruction, 474 

illegal instruction, 474 

line 1010 emulator, 474 

line 1111 emulator, 474 

privilege violation, 474 

trace, 474 

trap instructions, 474 

TRAPV instruction, 474 

zero divide, 474 
TRAP instruction, 469 
Traps, 474 

instructions, 476, 

supervisor mode, 475, 

trap handler, 475 
TRAPV instruction, 474 
Troubleshooting guide, 915 
TSTLIST, 498 
TSTLST2, 498 
TSTNODE, 498 
TTextAttr structure, 682 
Type 

of interrupt, 519, 

screen, 48 
TypeOfMem(), 459 
UCopList structure, 602 
UnlocklBaseO, 283, 289 
UnlockLayerQ, 707, 708 
UnlockLayerlnfoO, 708, 708 
UnlockLayersO, 708 
UnlockPubScreen(), 51, 56, 76 
UnlockPubScreenl_ist(), 54, 76 
Upfrontl_ayer(), 708, 71 1 
User Interface 

libraries, 24 
User stack, 477 
USEREQIMAGE, 204, 213 
UserExt, 651 
Using A Device, 447 
USP, 477 
Utility, 867 

32-bit math, 878 

callback hooks, 875 

date functions, 881 

function reference, 883 

international strings, 880 

tags, 867 
Vanilla Key, 277 

queue limit, 277 
VBEAM counter, 601 
VBR, 517 
Verify 

requester, 21 1 , 

window sizing, 91 
VERTB, 519, 525 
VERTB interrupts, 519, 525 
VertBServer, 527 
VGA Mode 3 

851 4/A, 537, 561 
Video Parameters 

Intuition control, 38 
Video priority 

in dual-playfield mode, 545 
VideoControlQ, 59, 63, 86, 545, 550, 553, 564, 603, 608, 61 1 

ColorMap, 564 

genlock, 607 
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ViewPort, 564 
View 

origin, 62, 

preparing, 551 
View Structure, 64, 66, 551 

function, 540 
ViewAddressf), 64, 76 
ViewExtra, 551 
ViewExtra structure, 568 
ViewPort 

and Simple Sprite colors, 618 

ColorMap, 542 

colors, 543, 553 

display instructions, 555 

display memory, 549 

displaying, 541 

function, 541 

Height, 542 

interlaced, 548 

low-resolution, 553 

modes, 544, 545 

Modes in Release 2, 564 

multiple, 553 

parameters, 542 

Width, 543 

width of and sprite display, 543 
ViewPort Structure, 39, 64, 66, 187, 552 
ViewPortAddress(), 64, 76 
ViewPortExtra, 551 
ViewPortExtra Structure, 59, 63, 86, 551, 553 

DisplayClip, 46 
Virtual terminal, 27 

window, 77 
Visible Area 

screen, 40 
Visible Display 

easy request, 217 
Visitor Window, 82 
VSOVERFLOW Flag 

in VSprite structure, 624, 

reserving Sprites, 632 
VSprite 

building the Copper list, 628 

changing, 627 

color, 626 

hardware Sprite assignment, 628, 633 

Playfield colors, 633 

position, 624 

shape, 625 

simple definition, 614 

size, 625 

sorting the GEL list, 628 

troubleshooting, 632 
VSprite Flags 

and True VSprites, 624 
VTAGJJSERCLIP_SET, 603 
VUserStuff, 651 
WA_Activate, 91, 110 
WA_AutoAdjust, 108, 111 
WA_Backdrop, 92, 110 
WA_BlockPen, 106 
WA_Borderless, 93, 110 
WA_Checkmark, 107, 181 
WA_CloseGadget, 107, 109 
WACustomScreen, 82, 107 
WA_DepthGadget, 1 07, 109 
WA_DetailPen, 106 
WA_DragBar, 107, 109 
WA_Flags, 106, 111, 175 
WA_Gadgets, 1 07 
WAGimmeZeroZero, 93, 1 10 
WAJHeight, 106 
WAJDCMP, 90, 107, 186 
WAJnnerHeight, 108 
WAJnnerWidth, 108 
WA_l_eft, 106 
WAJvlaxHeight, 108 
WAJvlaxWidth, 108 
WAJvlenuHelp, 1 1 1 , 179, 258, 260 
WAJvlinHeight, 108 
WAJvlinWidth, 108 
WAMouseQueue, 108, 114, 269 
WA_NoCareRefresh, 97, 110 



WA_PubScreen, 83, 108 

WA_PubScreenFallBack, 53, 83, 1 08 

WAPubScreenName, 53, 83, 108 

WA ReportMouse, 109, 258 

WA_RMBTrap, 110, 251, 258 

WA_RptQueue, 108, 114, 277 

WA_ScreenTitle, 107 

WA_SimpleRefresh, 110, 261 

WA_SizeBBottom, 1 09 

WA_SizeBRight, 109 

WA_SizeGadget, 109 

WA_SmartRefresh, 1 1 0, 261 

WA_SuperBitMap, 98, 1 1 1 

WA_Title, 107 

WA_Top, 1 06 

WAJA/idth, 1 06 

WA_Zoom, 107, 108 

Wait(), 30, 31 , 250, 432, 449, 470, 471 , 483, 485, 505 

WaitBlitO, 587, 592, 599, 599, 612 

WaitBOVP(), 560 

WaitlO(), 449, 451 

WaitPortO, 449, 504 

WaitTOFf), 560, 629 

WBenchToBack(), 52, 76 

WBenchToFront(), 52, 76 

WFLG_ACTIVATE, 91, 110 

WFLG_BACKDROP, 92, 110 

WFLG_BORDERLESS, 88, 93, 110 

WFLG_CI_OSEGADGET, 109 

WFLGJ3EPTHGADGET, 109 

WFLG_DRAGBAR, 109 

WFLGJ3IMMEZEROZERO, 93, 96, 110 

WFLGJMOCAREREFRESH, 97, 110 

WFLG_NW_EXTENDED, 80, 106 

WFLG_REPORTMOUSE, 109, 273 

WFLG_RMBTRAP, 49, 1 1 0, 1 1 1 , 1 75, 268 

setting, 110 
WFLG_SIMPLE_REFRESH, 110 
WFLG_SIZEBBOTTOM, 109, 126 
WFLG_SIZEBRIGHT, 109, 126 
WFLG_SIZEGADGET, 109 
WFLG_SMART_REFRESH, 110, 205 
WFLG_SUPER_BITMAP, 98, 111 
WFLG_WINDOWCLOSE, 107 
WFLGJ/VINDOWDEPTH, 107 
WFLGJ/VINDOWDRAG, 107 
WFLGJ/VINDOWSIZING, 108 
WhichLayer(), 708 
White Boxes-The Transparent Base Classes 

Boopsi, 316 
Width 

by inner dimension, 1 08 
Width variable 
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in VSprite structure, 625 
Window, 917 

activate message, 261 

advantages over menus, 170 

automatic size adjust, 1 1 1 

backdrop window type, 92 

borderless window type, 93 

borders, 932 

change message, 263 

close message, 259 

defined, 27 

dimensions, 85 

Examples 

calculating window border size, 89 

opening a window with tags, 80 

superbitmap window, 99 

using public screens, 83 

window sized to the visible display, 86 

GimmeZeroZero window type, 93 

inactive message, 261 

maximum height, 108 

maximum width, 108 

menus, 169 

minimum height, 108 

minimum width, 108 

new size message, 260 

pointer position, 273 



position change notify, 91 

positioning, 40 

problems, 921, 921 

refresh message, 261 

requester limit, 204 

simple refresh, 94 

size change notify, 91 

size limits, 108 

size verify message, 261 

smart refresh, 94 

super bit map, 94 

user positioning, 77 
Window structure, 219, 235, 273 

1.3 compatible usage, 19 

BorderBottom, 88, 89, 1 05 

BorderLeft, 88, 89, 1 05 

BorderRight, 88, 89, 105 

BorderRPort, 105 

BorderTop, 88, 89, 105 

definition, 104 

FirstRequest, 214 

Flags, 110, 186 

GZZHeight, 93 

GZZMouseX, 93, 105,273 

GZZMouseY, 93, 105,273 

GZZWidth, 93 

Height, 89, 105 

IDCMPFIags, 249-250 

LeftEdge, 105 

MessageKey, 249 

MouseX, 105,269 

MouseY, 105,269 

ReqCount, 105 

RPort, 105 

TopEdge, 105 

UserData, 105 

UserPort (IDCMP), 31, 249, 253-254, 257 

Width, 89, 105 

WindowPort, 249, 253-254 

WScreen, 105 
WindowLimitsQ, 89, 108, 115 
WindowToBack(), 112, 113, 115 
WindowToFrontQ, 112, 113, 115 
Workbench, 25, 52, 929 

AppMessage, 359 

close screen, 52 

introduction, 25 

open screen, 52 

screen, 75, 933 

screen to back, 52 

screen to front, 52 

shortcut key functions, 281 

stack size, 352 

startup code, 364 

startup message, 364 

start-up message, 364 

ToolTypes, 354 

windows on screen, 82 

.info file, 345 
WriteChunkBytes(), 787 
WriteChunkRecordsQ, 787 
WritePixelf), 587, 611 
XorRectRegionQ, 722 
XorRegionRegion(), 722 
Z, 525 

Zero divide, 474 
ZipWindow(), 112, 113, 115 
Zoom, 113 

alternate size, 78, 108 

enable gadget, 108 

ZipWindow(), 112, 113 
Zorro II 

see Expansion, AUTOCONFIG 
Zorro III 

see Expansion, AUTOCONFIG 

Index 967 



